Universal MCP Gateway

Convert any REST API into an MCP (Model Context Protocol) server that AI agents can use. Enable Claude, ChatGPT, and other AI assistants to interact with your APIs without writing custom integration code.

What is MCP?

Model Context Protocol (MCP) is Anthropic's open standard for connecting AI systems to external tools and data sources. With MCP, AI agents can:

• Call API endpoints as tools
• Read and write data through your APIs
• Perform complex workflows across multiple services

This actor bridges the gap between any REST API and MCP-compatible AI agents.

Features

• OpenAPI Auto-Discovery: Point to any OpenAPI 3.x spec and automatically generate MCP tools
• Manual Endpoint Definition: Define endpoints manually for APIs without OpenAPI specs
• Multiple Auth Methods: API Key, Bearer Token, Basic Auth, OAuth2 Client Credentials
• Response Caching: Reduce API calls with configurable TTL caching
• Rate Limiting: Protect target APIs with token bucket rate limiting
• Standby Mode: Run as a persistent HTTP server for real-time MCP requests

Quick Start

1. Using an OpenAPI Spec

{
  "apiSpec": "https://petstore3.swagger.io/api/v3/openapi.json",
  "authentication": {
    "type": "apiKey",
    "apiKey": "special-key",
    "apiKeyHeader": "api_key"
  }
}

This automatically generates MCP tools for all endpoints in the Petstore API.

2. Manual Endpoint Definition

{
  "baseUrl": "https://api.example.com",
  "manualEndpoints": [
    {
      "name": "getUser",
      "method": "GET",
      "path": "/users/{id}",
      "description": "Fetch a user by ID",
      "parameters": [
        {
          "name": "id",
          "type": "string",
          "in": "path",
          "required": true
        }
      ]
    },
    {
      "name": "createUser",
      "method": "POST",
      "path": "/users",
      "description": "Create a new user",
      "parameters": [
        {
          "name": "name",
          "type": "string",
          "in": "body",
          "required": true
        },
        {
          "name": "email",
          "type": "string",
          "in": "body",
          "required": true
        }
      ]
    }
  ],
  "authentication": {
    "type": "bearer",
    "apiKey": "your-api-token"
  }
}

Authentication Options

API Key

{
  "authentication": {
    "type": "apiKey",
    "apiKey": "your-api-key",
    "apiKeyHeader": "X-API-Key",
    "apiKeyIn": "header"
  }
}

Bearer Token

{
  "authentication": {
    "type": "bearer",
    "apiKey": "your-bearer-token"
  }
}

Basic Auth

{
  "authentication": {
    "type": "basic",
    "username": "user",
    "password": "pass"
  }
}

OAuth2 Client Credentials

{
  "authentication": {
    "type": "oauth2",
    "oauth2ClientId": "your-client-id",
    "oauth2ClientSecret": "your-client-secret",
    "oauth2TokenUrl": "https://auth.example.com/oauth/token",
    "oauth2Scopes": ["read", "write"]
  }
}

Using the MCP Server

In Standby Mode

When running in Standby mode, the actor exposes HTTP endpoints:

Endpoint	Method	Description
/health	GET	Health check with server stats
/tools	GET	List all available MCP tools
/mcp	POST	MCP JSON-RPC 2.0 endpoint

MCP Request Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Calling a Tool

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "getpetbyid",
    "arguments": {
      "petId": 123
    }
  }
}

Response Format

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\": 123, \"name\": \"Fluffy\", \"status\": \"available\"}"
      }
    ]
  }
}

Connecting to Claude Desktop

1. Run this actor in Standby mode on Apify
2. Copy the Standby URL (e.g., https://your-actor-id.apify.actor)
3. Add to Claude Desktop's MCP configuration:

{
  "mcpServers": {
    "my-api": {
      "url": "https://your-actor-id.apify.actor/mcp"
    }
  }
}

Configuration Options

Parameter	Type	Default	Description
apiSpec	string	-	OpenAPI spec URL or JSON
manualEndpoints	array	-	Manual endpoint definitions
baseUrl	string	-	API base URL
authentication	object	{type: "none"}	Auth configuration
caching	boolean	false	Enable response caching
cacheTtlSeconds	number	300	Cache TTL (1-86400)
rateLimitPerMinute	number	60	Max requests/minute

Output

When not running in Standby mode, the actor outputs:

{
  "message": "MCP Gateway initialized successfully",
  "baseUrl": "https://api.example.com",
  "toolCount": 15,
  "tools": [
    {
      "name": "getpetbyid",
      "description": "Returns a single pet",
      "inputSchema": {
        "type": "object",
        "properties": {
          "petId": {
            "type": "integer",
            "description": "ID of pet to return"
          }
        },
        "required": ["petId"]
      }
    }
  ]
}

Cost Estimation

• Standard run: ~$0.001 per run (just generates tool definitions)
• Standby mode: ~$0.025/hour while idle + compute costs when handling requests
• Target API costs: Depends on the API you're connecting to

Use Cases

1. AI-Powered Customer Support: Let Claude access your CRM, ticketing system, and knowledge base
2. Data Analysis: Enable AI to query your analytics APIs and generate insights
3. DevOps Automation: Allow AI agents to check deployment status, trigger builds, manage infrastructure
4. E-commerce: Connect AI to inventory, orders, and customer APIs for intelligent assistance
5. Internal Tools: Make any internal API accessible to AI assistants for employee productivity

Troubleshooting

"No endpoints found"

• Ensure your OpenAPI spec is valid and accessible
• Check that the spec contains path definitions
• Try using manual endpoint definitions instead

"Authentication failed"

• Verify your API credentials are correct
• Check the authentication type matches your API's requirements
• For OAuth2, ensure the token URL is correct and accessible

"Rate limited"

• Increase rateLimitPerMinute if your API allows higher limits
• Enable caching to reduce duplicate requests

"Tool not found"

• Tool names are converted to lowercase with underscores
• Check the /tools endpoint for exact tool names

Support

• Report Issues
• MCP Documentation
• Apify Documentation

License

ISC