MCP Gateway

The Model Context Protocol (MCP) gateway exposes your tools using the MCP standard, enabling Claude, Cursor, Windsurf, and other MCP-compatible AI clients to discover and invoke your tools natively.

Overview

MCP is a JSON-RPC 2.0 based protocol for connecting AI models to external tools and data sources. almyty implements the full MCP specification, supporting:

Tool listing — tools/list method
Tool invocation — tools/call method
Multiple transports — HTTP, Server-Sent Events (SSE), WebSocket

Creating an MCP Gateway

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

Endpoint URL

After creation, your MCP endpoint is available at:

https://api.almyty.com/mcp/{org-slug}{endpoint}

For example, if your organization is "acme" and endpoint is "/my-tools":

https://api.almyty.com/mcp/acme/my-tools

Connecting Clients

Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "my-tools": {
      "url": "https://api.almyty.com/mcp/acme/my-tools",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

Cursor

In Cursor settings, add a new MCP server:

{
  "name": "my-tools",
  "url": "https://api.almyty.com/mcp/acme/my-tools",
  "apiKey": "your-api-key"
}

Custom MCP Client

import httpx
 
# List available tools
response = httpx.post(
    "https://api.almyty.com/mcp/acme/my-tools",
    json={
        "jsonrpc": "2.0",
        "method": "tools/list",
        "id": 1
    },
    headers={"Authorization": "Bearer your-api-key"}
)
tools = response.json()["result"]["tools"]
 
# Call a tool
response = httpx.post(
    "https://api.almyty.com/mcp/acme/my-tools",
    json={
        "jsonrpc": "2.0",
        "method": "tools/call",
        "params": {
            "name": "get_users",
            "arguments": {"page": 1, "limit": 10}
        },
        "id": 2
    },
    headers={"Authorization": "Bearer your-api-key"}
)
result = response.json()["result"]

Transport Options

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

MCP Tool Format

Tools exposed via MCP follow the MCP tool schema:

{
  "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": []
  }
}

Authentication

MCP gateways support all gateway authentication methods, including OAuth 2.1 with PKCE. MCP clients that support the OAuth flow will automatically discover the authorization server via:

GET /mcp/{org}/{endpoint}/.well-known/oauth-authorization-server

On 401 responses, the gateway returns a WWW-Authenticate header with a link to the protected resource metadata, allowing MCP clients to initiate the OAuth flow automatically.

For simpler setups, use API key or Bearer token auth via headers.

See Gateway Authentication for full details.

Error Responses

MCP errors follow the JSON-RPC 2.0 error format:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Invalid request"
  },
  "id": 1
}

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

Authentication A2A