Connect Portkey to Claude: Control Guardrails, Vector Stores & RAG

If your team uses Portkey to manage LLM observability, routing, and guardrails, you likely need a way to let AI agents orchestrate that infrastructure. Connecting Portkey to Claude allows your AI assistants to dynamically configure prompts, enforce safety guardrails, and audit telemetry. To do this securely, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Portkey's REST APIs.

You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting Portkey to ChatGPT or explore our broader architectural overview on connecting Portkey to AI Agents.

Giving a Large Language Model (LLM) read and write access to a complex AI gateway like Portkey is an engineering challenge. You have to handle API token lifecycles, map massive JSON schemas to MCP tool definitions, and deal with Portkey's specialized data models. Every time Portkey updates an endpoint or changes a gateway routing parameter, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Portkey, connect it natively to Claude Desktop, and execute complex AI engineering workflows using natural language.

The Engineering Reality of the Portkey API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against specialized B2B APIs is painful. Portkey is built to route, observe, and protect AI traffic. Its API reflects that complexity, and simply passing standard REST documentation to an LLM will result in hallucinations and failed requests.

If you decide to build a custom Portkey MCP server, here are the specific integration challenges you will face:

Prompt Versioning and Immutability Portkey treats prompts as immutable artifacts. You cannot simply use a PUT request to overwrite the text of an existing prompt. Instead, updating a prompt (update_a_portkey_prompt_by_id) requires creating a new version. Furthermore, if you want that new version to be used in production, you must execute a bulk update (portkey_prompt_make_defaults_bulk_update) to set it as the default. If an LLM tries to "edit" a prompt without understanding this versioning schema, it will fail. A managed MCP server provides exact schemas that guide the LLM through this multi-step process.

Complex Gateway Configuration Schemas Portkey configs control retries, fallbacks, load balancing, and caching. These configurations use deeply nested JSON structures (e.g., retry, cache, strategy, and targets). When an LLM attempts to write a configuration, it often guesses the nesting structure incorrectly or hallucinates deprecated fields. A dynamic MCP server derives its JSON Schema directly from the integration's documentation records, ensuring the LLM only generates valid, strictly typed configuration objects.

Hyperparameters vs Variables in Completions When executing a saved prompt template (create_a_portkey_prompt_completion), Portkey enforces a specific structural rule: hyperparameters (like temperature or max_completion_tokens) must be passed at the root level alongside the variables object, not nested inside it. Additionally, Portkey has deprecated the max_tokens parameter in favor of max_completion_tokens. A hand-rolled MCP server will frequently watch Claude fail because the LLM tries to inject max_tokens inside the variables block. A managed MCP server sanitizes the input schemas to enforce the correct structure.

How to Generate a Managed MCP Server for Portkey

Truto dynamically generates MCP tools by reading the underlying integration's documented resources and methods. You can generate a Portkey MCP server in two ways: via the Truto UI or programmatically via the REST API.

Method 1: Generating via the Truto UI

For administrators who prefer a visual interface, creating an MCP server takes just a few clicks:

1. Log into Truto and navigate to your Integrated Accounts.
2. Select your connected Portkey account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your configuration. You can filter the tools by method (e.g., only allow read operations) or apply tag filters if you only want to expose specific functional areas (like analytics or prompts).
6. Copy the generated MCP server URL. This URL contains a cryptographic token that securely identifies the account and configuration.

Method 2: Generating via the Truto API

For automated deployments, you can provision Portkey MCP servers dynamically. This is useful if you are building an AI agent platform and need to spin up isolated servers for individual tenants.

Make a POST request to the /integrated-account/:id/mcp endpoint:

curl -X POST https://api.truto.one/admin/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Portkey Observability Agent",
    "config": {
      "methods": ["read", "write"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The response will return a secure, ready-to-use URL:

{
  "id": "mcp_srv_9x8y7z6w",
  "name": "Portkey Observability Agent",
  "config": { "methods": ["read", "write"] },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6g7h8..."
}

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, you need to connect it to your Claude environment. All communication happens over HTTP POST with JSON-RPC 2.0 messages.

Method A: Via the Claude UI

If you are using Claude's web or enterprise interface (or a similar UI like ChatGPT's Custom Connectors):

1. Navigate to Settings -> Integrations (or Connectors).
2. Click Add MCP Server or Add Custom Connector.
3. Provide a name (e.g., "Portkey Control Plane").
4. Paste the Truto MCP URL into the Server URL field.
5. Click Add.

Claude will immediately send an initialize request to the server, discover all the available Portkey tools, and make them available for natural language prompting.

Method B: Via the claude_desktop_config.json

For developers using the Claude Desktop app, you connect remote MCP servers using Server-Sent Events (SSE). You will need to use the official @modelcontextprotocol/server-sse package to bridge Claude's local standard I/O to Truto's remote HTTP endpoint.

Edit your claude_desktop_config.json file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "portkey": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/YOUR_TRUTO_TOKEN"
      ]
    }
  }
}

Restart Claude Desktop. The application will execute the bridge command and pull the Portkey tool definitions into your workspace.

sequenceDiagram
    participant Claude as Claude Desktop
    participant SSE as SSE Bridge (npx)
    participant Truto as Truto MCP Server
    participant Portkey as Portkey API
    
    Claude->>SSE: Initialize connection
    SSE->>Truto: POST /mcp/TOKEN (tools/list)
    Truto-->>SSE: Return dynamic tool schemas
    SSE-->>Claude: JSON-RPC tools list
    
    Claude->>SSE: Call create_a_portkey_prompt
    SSE->>Truto: JSON-RPC tools/call
    Truto->>Portkey: POST /prompts
    Portkey-->>Truto: Return 200 OK
    Truto-->>SSE: Format response
    SSE-->>Claude: JSON-RPC Result

Hero Tools for Portkey Automation

Truto automatically generates descriptive snake_case tool names based on the underlying Portkey resources. Here are the most powerful tools to expose to Claude for AI engineering workflows.

create_a_portkey_prompt

This tool allows Claude to define and store new prompt templates within your Portkey workspace. It requires the prompt name, a collection ID, the raw string, and the desired parameters.

"I need to create a new system prompt for our customer support bot. Create a new prompt in Portkey named 'Support_Bot_V1' in collection 'col-8492'. The string should be 'You are a helpful assistant. User query: {{query}}'. Set the model to gpt-4o."

update_a_portkey_prompt_by_id

Portkey treats prompt content as immutable. To change a prompt, this tool actually generates a new version under the same prompt ID. Claude can use this to iteratively refine prompts based on evaluation feedback.

"Update the prompt 'pr-99382'. Create a new version where the system string includes instructions to never mention internal pricing. Inherit the rest of the settings from the current latest version."

create_a_portkey_guardrail

Guardrails enforce safety, compliance, and structure on your LLM traffic. This tool allows Claude to configure pre-execution checks (like PII redaction) or post-execution checks (like JSON validation).

"Create a new Portkey guardrail named 'PII_Scrubber'. Add a check to detect and redact credit card numbers and social security numbers. If triggered, the action should be to block the request entirely."

create_a_portkey_virtual_key

Virtual keys allow you to abstract provider credentials (like OpenAI or Anthropic API keys) behind a Portkey-managed key. Claude can use this tool to programmatically rotate or provision keys for new environments.

"Generate a new Portkey virtual key for our Anthropic provider integration. Name it 'Prod_Opus_Key' and set a usage limit of $500 per month."

list_all_portkey_graphs_costs

This tool queries Portkey's analytics engine to retrieve time-series cost data. Claude can use it to audit spend across different workspaces, models, or virtual keys.

"Pull the cost graph for the last 7 days from Portkey. Group the data by AI model so I can see if we are spending more on Claude 3.5 Sonnet or GPT-4o."

list_all_portkey_logs_exports

For deep telemetry analysis, Portkey requires exporting logs asynchronously. This tool allows Claude to initiate a bulk export of up to 50,000 logs based on specific filters (like trace IDs or status codes).

"Initiate a logs export for all requests in the last 24 hours that returned a 429 status code. I need to figure out which microservice is hitting the rate limit."

For the complete inventory of available Portkey operations and their detailed JSON schemas, view the Portkey integration page.

Workflows in Action

Exposing these tools to Claude transforms it from a chatbot into a capable AI infrastructure engineer. Here is how specific personas can automate Portkey workflows.

Scenario 1: Prompt Versioning and Refinement

Persona: Machine Learning Engineer

A model in production is hallucinating answers about shipping policies. The engineer needs to update the active prompt template quickly without leaving their IDE.

"Claude, check the current version of the prompt 'pr-shipping-bot'. The model is hallucinating shipping times. Update the prompt to explicitly state that standard shipping takes 5-7 business days. Once the new version is created, set it as the default version for production."

Execution Steps:

1. Claude calls get_single_portkey_prompt_by_id to retrieve the current template string and configuration.
2. Claude rewrites the string to include the new constraints.
3. Claude calls update_a_portkey_prompt_by_id, passing the modified string to create a new version (e.g., version 4).
4. Claude calls portkey_prompt_make_defaults_bulk_update to promote version 4 to the active default.

Result: The production prompt is updated and deployed instantly, fixing the hallucination without the engineer ever opening the Portkey dashboard.

Scenario 2: Setting up a Guardrailed AI Gateway

Persona: DevOps Administrator

A new internal application needs access to OpenAI, but security requires strict PII scrubbing and rate limiting before the traffic hits the provider.

"I need to configure Portkey for our new HR app. First, create a new virtual key for our OpenAI integration with a hard rate limit of 100 requests per minute. Then, create a guardrail that blocks any prompt containing Social Security Numbers. Finally, create a Portkey config that applies this guardrail and uses the new virtual key."

Execution Steps:

1. Claude calls create_a_portkey_virtual_key, passing the OpenAI provider ID and the rate limit policy.
2. Claude calls create_a_portkey_guardrail to define the PII blocking rules.
3. Claude calls create_a_portkey_config to bind the virtual key and the guardrail together into a deployable config slug.

Result: The DevOps admin receives a ready-to-use Portkey Config ID they can inject directly into the HR application's environment variables.

Scenario 3: Auditing AI Infrastructure Costs

Persona: AI Product Manager

The monthly cloud bill spiked, and the PM needs to know which models or workspaces are driving the cost.

"Analyze our Portkey cost data for the last 30 days. Pull the cost graph grouped by AI provider, and then pull the graph grouped by workspace. Tell me where the spike is coming from."

Execution Steps:

1. Claude calls list_all_portkey_graphs_costs with the group_by parameter set to provider.
2. Claude calls list_all_portkey_graphs_costs again, changing the grouping to workspace.
3. Claude synthesizes the time-series arrays returned by the API and formats a natural language summary.

Result: The PM gets a concise report indicating that the spike originated from an experimental workspace querying expensive embedding models, allowing them to take immediate corrective action.

Security and Access Control

Giving an AI agent access to your telemetry and prompt configurations requires strict security boundaries. Truto provides several mechanisms to lock down your Portkey MCP server:

• Method Filtering: You can restrict the MCP server to only allow read operations (e.g., fetching logs and viewing prompts), explicitly blocking the AI from creating or modifying configurations.
• Tag Filtering: Limit the available tools to specific functional areas. For example, you can create a server that only exposes tools tagged with analytics, hiding the prompt engineering and virtual key management endpoints.
• Dual-Layer Authentication (require_api_token_auth): By default, the cryptographically secure MCP URL acts as the authentication token. For zero-trust environments, you can enable dual-layer auth, forcing the MCP client to also pass a valid Truto API token in the Authorization header to execute tools.
• Automatic Expiration (expires_at): You can generate ephemeral MCP servers that automatically self-destruct after a specific timestamp, which is ideal for granting a contractor temporary access to audit your Portkey setup.

Handling Rate Limits at Scale

When an AI agent rapidly executes tools, it can trigger upstream rate limits. It is important to understand how Truto handles these constraints. Truto does not automatically retry, throttle, or apply backoff logic on rate limit errors.

If Portkey returns an HTTP 429 Too Many Requests error, Truto passes that error directly back to the MCP client (Claude). Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller (or the orchestrating agent framework) is entirely responsible for reading these headers and implementing its own retry or backoff logic.

Take Control of Your AI Gateway

Connecting Portkey to Claude via Truto's MCP server transforms your AI assistant into a fully capable AI operations engineer. By exposing dynamic, schema-accurate tools, you allow Claude to manage prompts, configure guardrails, and audit telemetry safely and predictably. You avoid the hidden costs of building point-to-point integrations, managing OAuth tokens, and fixing broken schemas every time an API updates.

Stop writing boilerplate integration code. Let Truto generate the tools your agents need to orchestrate the world's most powerful SaaS platforms.