Skip to main content

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 18+ installed
  • An MCP-compatible client (Claude Desktop, Cursor, or VS Code)
  • At least one MCP server to connect to

​
Quick Start

Get your MCP Gateway running in three simple steps.
1

Install and run the gateway

Start the Portkey AI Gateway with MCP support:
# Run the gateway locally
npx @portkey-ai/gateway
The gateway will start on http://localhost:8787 with MCP endpoints available at /mcp/*.
For production deployments, see our deployment guides.
2

Configure your MCP servers

Create a configuration file mcp-config.json to define your MCP servers:
mcp-config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
      "description": "File system access for workspace"
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      },
      "description": "GitHub repository access"
    }
  },
  "auth": {
    "type": "bearer",
    "enabled": true
  }
}
This configuration defines two MCP servers: one for filesystem access and one for GitHub integration. The gateway will manage authentication and routing to these servers.
3

Connect your MCP client

Configure your MCP client to use the gateway. For Claude Desktop, update your config file:macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "portkey-gateway": {
      "url": "http://localhost:8787/mcp",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer your-gateway-token"
      }
    }
  }
}
Replace your-gateway-token with a valid authentication token from your gateway instance.

​
Verify the Setup

Once configured, verify that your MCP Gateway is working:
  1. Check gateway status: Visit the gateway console at http://localhost:8787/public/
  2. Test server connection: The gateway will show connected MCP servers and their status
  3. Use tools in your client: Open Claude Desktop (or your MCP client) and try using the connected tools
You should see your MCP servers listed as available tools in your client. Try asking Claude to “list available files” to test the filesystem server.

​
View Logs and Monitoring

The gateway automatically logs all MCP interactions: 
# View real-time logs
curl http://localhost:8787/mcp/logs
Or visit the gateway console to see:
  • Active connections
  • Tool call history
  • Performance metrics
  • Error logs

​
Example: Using the Gateway

Once connected, your MCP client can use tools through the gateway: In Claude Desktop: 
You: Can you list the files in my workspace?

Claude: I'll use the filesystem tool to check...
[Gateway logs: User [email protected] called filesystem.listFiles]

Claude: Here are the files in your workspace:
- src/
- tests/
- README.md
- package.json
The gateway automatically:
  • Authenticated the request from [email protected]
  • Checked that Alice has permission to use the filesystem tool
  • Forwarded the request to the MCP server
  • Logged the complete interaction
  • Returned the response to Claude

​
Next Steps

Now that you have MCP Gateway running, explore advanced features:

Authentication

Set up SSO and advanced auth methods

Access Control

Configure granular permissions

Production Deployment

Deploy to production environments

Monitoring

Set up monitoring and alerts

​
Troubleshooting

Check that:
  • Port 8787 is not already in use
  • Node.js 18+ is installed
  • You have proper file permissions
Try running with debug logs:
DEBUG=* npx @portkey-ai/gateway
Verify:
  • Gateway is running and accessible
  • Client configuration has correct URL
  • Authentication token is valid
  • Firewall rules allow connections
Check:
  • Server commands are correct in config
  • Required environment variables are set
  • Servers have necessary permissions
  • Gateway logs for specific error messages
Common issues:
  • Token expired or invalid
  • User doesn’t have required permissions
  • Auth configuration mismatch
  • Check gateway logs for specific auth errors
Need help? Join our Discord community or check the GitHub issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us