MCP Gateway

The Model Context Protocol (MCP) gateway exposes your tools via JSON-RPC 2.0 to any MCP-compatible client, including Claude, Cursor, Windsurf, and VS Code Copilot. almyty supports HTTP, SSE, and WebSocket transports.

Gateways page

In the UI

Navigate to Gateways in the sidebar
Click Create Gateway
Select MCP as the protocol

Create Gateway dialog

Enter a name, slug (used in the endpoint URL), and optional description
Under Transport, choose HTTP (default), SSE, or WebSocket
Click Create
On the gateway detail page, open the Tools tab to assign tools

Gateways page — empty state

Use the Authentication tab to add an auth method before going live

Your MCP endpoint is available at:


/{org-slug}/{gateway-slug}

Via the API

Create a gateway


curl -X POST /gateways \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My MCP Gateway",
    "type": "mcp",
    "endpoint": "/my-tools",
    "configuration": {
      "transport": "http"
    }
  }'

List tools (JSON-RPC)


curl -X POST /acme/my-tools \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Call a tool (JSON-RPC)


curl -X POST /acme/my-tools \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_users",
      "arguments": { "page": 1, "limit": 10 }
    },
    "id": 2
  }'

Transport options

Transport	URL pattern	Use case
HTTP	`POST /{org}/{slug}`	Standard request-response
SSE	`GET /{org}/{slug}/sse`	Streaming, long-running tools
WebSocket	`WS /{org}/{slug}/ws`	Bidirectional, real-time

Connecting clients

Claude Desktop

Add to claude_desktop_config.json:


{
  "mcpServers": {
    "my-tools": {
      "url": "https://your-instance/acme/my-tools",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

Cursor

In Cursor settings, add:


{
  "name": "my-tools",
  "url": "https://your-instance/acme/my-tools",
  "apiKey": "your-api-key"
}

MCP tool schema

Tools exposed through the gateway follow the MCP tool format:


{
  "name": "get_users",
  "description": "Retrieve a list of users with pagination",
  "inputSchema": {
    "type": "object",
    "properties": {
      "page": { "type": "integer", "description": "Page number" },
      "limit": { "type": "integer", "description": "Items per page" }
    },
    "required": []
  }
}

OAuth 2.1

MCP gateways with OAuth enabled expose discovery endpoints automatically:


# Authorization server metadata
curl /acme/my-tools/.well-known/oauth-authorization-server
 
# Protected resource metadata
curl /acme/my-tools/.well-known/oauth-protected-resource

On 401 responses, the gateway returns a WWW-Authenticate header linking to the protected resource metadata so MCP clients can initiate the OAuth flow automatically. See Gateway Authentication for the full OAuth 2.1 walkthrough.

Error codes

MCP errors follow JSON-RPC 2.0:

Code	Meaning
`-32700`	Parse error
`-32600`	Invalid request
`-32601`	Method not found
`-32602`	Invalid params
`-32603`	Internal error