Using MCP Servers

Connect to MCP servers from AI agents and applications.

After an admin provisions MCP servers to your workspace, connect from any MCP client—Claude Desktop, Cursor, VS Code, or custom applications.

Find your connection URL

Go to MCP in your workspace sidebar. Click on a server to see its connection details.

Each server has a URL:

https://mcp.portkey.ai/{server-slug}/mcp

Copy this URL to use in your agent configuration.

For self-hosted deployments, replace mcp.portkey.ai with your gateway URL.

---

MCP Clients

Claude Desktop

Add to your Claude Desktop config file.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "linear": {
      "url": "https://mcp.portkey.ai/linear/mcp",
      "headers": {
        "x-portkey-api-key": "YOUR_PORTKEY_API_KEY"
      }
    }
  }
}

Restart Claude Desktop after saving. The tools appear in your conversation.

For OAuth-enabled servers, Claude prompts for authentication on first tool use.

Cursor

Open Cmd/Ctrl + Shift + P > Cursor Settings: Open MCP Settings.

{
  "mcpServers": {
    "linear": {
      "url": "https://mcp.portkey.ai/linear/mcp",
      "headers": {
        "x-portkey-api-key": "YOUR_PORTKEY_API_KEY"
      }
    }
  }
}

The tools are available in Cursor’s agent mode.

VS Code

With GitHub Copilot and the MCP extension:

{
  "mcp.servers": {
    "linear": {
      "url": "https://mcp.portkey.ai/linear/mcp",
      "headers": {
        "x-portkey-api-key": "YOUR_PORTKEY_API_KEY"
      }
    }
  }
}

---

Transport

MCP Gateway uses HTTP Streamable transport for all connections. This is the standard MCP transport that supports bidirectional communication over HTTP.

Sessions are ephemeral—each request is independent. There’s no session persistence between requests, which simplifies scaling and removes the need for sticky sessions.

---

SDKs

Python

pip install mcp

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

url = "https://mcp.portkey.ai/linear/mcp"
headers = {"x-portkey-api-key": "YOUR_PORTKEY_API_KEY"}

async with streamablehttp_client(url, headers=headers) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        
        # List tools
        tools = await session.list_tools()
        for tool in tools.tools:
            print(f"{tool.name}: {tool.description}")
        
        # Call a tool
        result = await session.call_tool(
            "create_issue",
            {"title": "Bug report", "priority": "high"}
        )
        print(result)

TypeScript

npm install @modelcontextprotocol/sdk

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.portkey.ai/linear/mcp"),
  {
    requestInit: {
      headers: { "x-portkey-api-key": "YOUR_PORTKEY_API_KEY" }
    }
  }
);

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

const tools = await client.listTools();
console.log(tools);

const result = await client.callTool({
  name: "search_issues",
  arguments: { query: "bug" }
});
console.log(result);

---

API Keys

Create API keys in Settings > API Keys. Keys are scoped to workspaces, so the key determines which MCP servers your agent can access.

When creating your workspace API key, ensure it has MCP Invoke permissions enabled.

---

Handling OAuth

MCP servers with OAuth require users to complete consent before using tools.

The first time a user calls a tool, Portkey returns an error with an authorization URL. Redirect the user to complete OAuth. After consent, retry the request.

try:
    result = await session.call_tool("get_repos", {})
except Exception as e:
    if "authorization_url" in str(e):
        # Redirect user to authorize
        print(f"Please authorize: {authorization_url}")

After authorization, Portkey stores the user’s tokens and handles refresh automatically.

---

AI Gateway Integration

For Portkey AI Gateway users, MCP integrates automatically:

• Unified dashboard for LLM and MCP activity
• Traces span model calls and tool use
• Single API key for both services

---

Next Steps

Authentication

Authentication options for MCP Gateway.

Observability

Monitor MCP traffic and debug issues.