@vtex/developer-mcp

An MCP server that gives AI coding assistants direct access to VTEX documentation and API references.

What is this?

@vtex/developer-mcp is a Model Context Protocol server for commerce developers building on VTEX. It gives your AI coding assistant the ability to search documentation, retrieve full articles, and look up API endpoint specifications — all from within your editor.

No API key or authentication required. Just add the config to your editor and start asking questions.

Quick Start

The fastest setup: create or edit .cursor/mcp.json in your project (or ~/.cursor/mcp.json for global access) and paste this:

{
  "mcpServers": {
    "vtex-developer": {
      "command": "npx",
      "args": ["-y", "@vtex/developer-mcp"]
    }
  }
}

That's it. See below for all platforms.

Platform Setup

Each platform uses slightly different JSON keys. The configs below are exact — copy them as-is.

Cursor

File: .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

{
  "mcpServers": {
    "vtex-developer": {
      "command": "npx",
      "args": ["-y", "@vtex/developer-mcp"]
    }
  }
}

VS Code / GitHub Copilot

File: .vscode/mcp.json

Note: VS Code uses "servers" as the top-level key, not "mcpServers".

{
  "servers": {
    "vtex-developer": {
      "command": "npx",
      "args": ["-y", "@vtex/developer-mcp"],
      "type": "stdio"
    }
  }
}

Claude Code

Run this in your terminal:

claude mcp add vtex-developer -- npx -y @vtex/developer-mcp

Or add a .mcp.json file at your project root (shareable with your team):

{
  "mcpServers": {
    "vtex-developer": {
      "command": "npx",
      "args": ["-y", "@vtex/developer-mcp"]
    }
  }
}

Claude Desktop

1. Open Claude Desktop and click the Claude menu in the menu bar
2. Select Settings... → Developer tab
3. Click Edit Config — this opens claude_desktop_config.json
4. Add the following to the file and save:

{
  "mcpServers": {
    "vtex-developer": {
      "command": "npx",
      "args": ["-y", "@vtex/developer-mcp"]
    }
  }
}

5. Quit and reopen Claude Desktop for the changes to take effect

Supported Platforms

| Platform | Config Format | Setup Complexity | |---|---|---| | Cursor | JSON | Simple | | VS Code / GitHub Copilot | JSON | Simple | | Claude Code | CLI or JSON | Simple | | Claude Desktop | JSON | Simple |

Available Tools

Once connected, your AI assistant has access to these tools:

| Tool | Description | Key Parameters | |---|---|---| | search_documentation | Hybrid semantic + keyword search across VTEX Help Center and Developer Portal | query (required), locale (en, es, pt — required), limit (1–50), format | | fetch_document | Retrieve the full content of a VTEX documentation article by URL | url (required), format | | search_endpoints | Search VTEX API endpoints by query over OpenAPI definitions | query (required), limit (1–50), method (GET, POST, etc.), format | | get_endpoint_details | Get the full OpenAPI specification for a specific endpoint | endpoint_id (required), format |

search_documentation returns ranked results with titles, URLs, and content excerpts. Use fetch_document to pull the full text of any article the search surfaces.

search_endpoints finds API endpoints matching your query. Use get_endpoint_details with the returned endpoint ID to get the complete specification including parameters, request/response schemas, and server URLs.

All tools support a format parameter (markdown, json, yaml, toml) — defaults to markdown.

Usage Examples

After setup, you can ask your AI assistant things like:

• "Search VTEX documentation for payment provider integration"
• "Fetch the full guide at https://developers.vtex.com/docs/guides/payments-integration-payment-provider-protocol"
• "Find documentation about the catalog API"
• "Search for API endpoints related to order placement"
• "Get the full specification for the Create Order endpoint"

The assistant will call the MCP tools automatically and ground its answers in the actual documentation.

Troubleshooting

Node.js not installed This package requires Node.js 18 or later. Check your version with node --version and install from nodejs.org if needed.

npx not found npx ships with Node.js. If it's missing, reinstalling Node.js should fix it.

Server not connecting Make sure you have internet access. The server needs to reach the VTEX documentation backend on startup. If you're behind a corporate firewall, check that outbound HTTPS connections are allowed.

Server not appearing in MCP client Restart your editor after adding the config. Some clients (Claude Desktop in particular) require a full restart to pick up new MCP servers.

VS Code: tools not appearing Use "servers" as the top-level key in .vscode/mcp.json, not "mcpServers". The VS Code MCP extension uses its own schema.

Testing

For development and contribution guidelines, including how to run tests, see CONTRIBUTING.md.

License

MIT