portkey-admin-mcp — Claude Code MCP server: how to install
Connects coding agents to the Portkey control plane. It helps configure gateway routing, prompt versions, budgets, and keys directly inside the editor.
claude mcp add --env PORTKEY_API_KEY=<PORTKEY_API_KEY> --env PORTKEY_TOOL_DOMAINS=<PORTKEY_TOOL_DOMAINS> --env PORTKEY_BASE_URL=<PORTKEY_BASE_URL> --transport stdio portkey-admin-mcp -- npx -y portkey-admin-mcpWhat portkey-admin-mcp does
This server exposes the Portkey control plane to coding assistants through its Admin API. It provides 194 tools covering prompt versions and gateway routing configs. Running it requires Node.js 24 or newer. You also need a valid PORTKEY_API_KEY.
Loading the entire 194-tool catalog takes roughly 400 KB across paginated requests. Without PORTKEY_TOOL_DOMAINS, tool definitions consume prompt context immediately. Passing specific domains like prompts,analytics cuts payload size down. That keeps your chat responsive.
The implementation expects Portkey authentication via the x-portkey-api-key header. Pointing PORTKEY_BASE_URL at Prisma AIRS will not work because Prisma uses separate authentication schemes. You can execute the package directly via npx or build the TypeScript code from source.
What it helps with
- Manage versions and partials for Portkey prompts
- Configure gateway routing, retries, and load balancing
- Set up guardrails and access policies for LLM models
- Monitor spend budgets and token usage limits
- Manage provider virtual keys and external secrets
Example prompts for the agent
- Update the Portkey gateway config to balance traffic between two providers.
- Check current token consumption and budget limits in my Portkey account.
- Create a new prompt version for customer support and tag it with
staging.
How to install portkey-admin-mcp
Platform CLI
claude mcp add --env PORTKEY_API_KEY=<PORTKEY_API_KEY> --env PORTKEY_TOOL_DOMAINS=<PORTKEY_TOOL_DOMAINS> --env PORTKEY_BASE_URL=<PORTKEY_BASE_URL> --transport stdio portkey-admin-mcp -- npx -y portkey-admin-mcpReplace <…> with your own values
Platform CLI
codex mcp add portkey-admin-mcp --env PORTKEY_API_KEY=<PORTKEY_API_KEY> --env PORTKEY_TOOL_DOMAINS=<PORTKEY_TOOL_DOMAINS> --env PORTKEY_BASE_URL=<PORTKEY_BASE_URL> -- npx -y portkey-admin-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"portkey-admin-mcp": {
"command": "npx",
"args": [
"-y",
"portkey-admin-mcp"
],
"env": {
"PORTKEY_API_KEY": "<PORTKEY_API_KEY>",
"PORTKEY_TOOL_DOMAINS": "<PORTKEY_TOOL_DOMAINS>",
"PORTKEY_BASE_URL": "<PORTKEY_BASE_URL>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"portkey-admin-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"portkey-admin-mcp"
],
"env": {
"PORTKEY_API_KEY": "<PORTKEY_API_KEY>",
"PORTKEY_TOOL_DOMAINS": "<PORTKEY_TOOL_DOMAINS>",
"PORTKEY_BASE_URL": "<PORTKEY_BASE_URL>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e PORTKEY_API_KEY=<PORTKEY_API_KEY> -e PORTKEY_TOOL_DOMAINS=<PORTKEY_TOOL_DOMAINS> -e PORTKEY_BASE_URL=<PORTKEY_BASE_URL> portkey-admin-mcp npx -y portkey-admin-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about portkey-admin-mcp
How do I install portkey-admin-mcp in Claude Code?
Run claude mcp add portkey-admin-mcp -e PORTKEY_API_KEY=<PORTKEY_API_KEY> -- npx -y portkey-admin-mcp in your terminal, replacing <PORTKEY_API_KEY> with your actual token.
What does portkey-admin-mcp do?
It provides control-plane management for Portkey directly within MCP clients, letting you adjust gateway settings, organize prompts, enforce guardrails, and inspect limits.
How do I reduce context token usage with this server?
Set the PORTKEY_TOOL_DOMAINS environment variable to a comma-separated list of domains, such as prompts,analytics. This limits loaded tools and prevents context bloat.
