atlas-mcp-server

Local stdio MCP server that proxies to the Atlas MCP Remote on AWS Lambda.

Use this package with Cursor, Claude Desktop, or Claude Code when you need a local MCP process (stdio) instead of connecting directly to the HTTP endpoint.

| Tool | Description | |------|-------------| | retrieve_context | Semantic search over the VTEX Atlas Bedrock Knowledge Base | | get_architecture | Fetch a VTEX client's solution architecture document from S3 |

Tools are discovered dynamically from the remote server — when new tools are added to Atlas MCP Remote, this proxy exposes them automatically.

Usage with Claude Code

claude mcp add atlas-remote -- npx -y @miguel-carrera/atlas-mcp-server

Or add to your claude_desktop_config.json / .cursor/mcp.json:

{
  "mcpServers": {
    "atlas-remote": {
      "command": "npx",
      "args": ["-y", "@miguel-carrera/atlas-mcp-server"],
      "env": {
        "ATLAS_MCP_URL": "https://<api-id>.execute-api.us-east-1.amazonaws.com/mcp",
        "ATLAS_MCP_TOKEN": "<your-token>",
        "ATLAS_MCP_EMAIL": "[email protected]"
      }
    }
  }
}

Prerequisites

• Node.js ≥ 18
• A valid token from the atlas-mcp-tokens DynamoDB table
• The token's email field must match ATLAS_MCP_EMAIL

Configuration

| Environment variable | Required | Description | |---|---|---| | ATLAS_MCP_URL | Yes | Remote MCP endpoint URL (must end with /mcp) | | ATLAS_MCP_TOKEN | Yes | Bearer token for authentication | | ATLAS_MCP_EMAIL | Yes | User email — must match the token record |

How it works

Cursor / Claude Desktop  →  stdio  →  atlas-mcp-server (this package)
                                           │
                                           │  HTTP POST /mcp (JSON-RPC)
                                           ▼
                                    API Gateway → Lambda (Atlas MCP Remote)
                                                    ├── Bedrock (retrieve_context)
                                                    └── S3 (get_architecture)

The local server forwards tools/list and tools/call JSON-RPC requests to the remote HTTP API with Authorization: Bearer <token> and X-User-Email headers.

Development

cd client
npm install
npm run dev      # watch mode
npm run build    # compile to dist/

Run locally with your credentials:

ATLAS_MCP_URL=https://<api-id>.execute-api.us-east-1.amazonaws.com/mcp \
ATLAS_MCP_TOKEN=<token> \
[email protected] \
npm start

Publish

cd client
npm publish --access public