--- description: Run the Claude Agent SDK through an AI gateway for routing, failover, per-tenant budgets, and governed MCP tool access, with Python and TypeScript setup. title: "Claude Agent SDK Through a Gateway: Routing, Budgets, MCP" image: https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w1200/2026/10/claude-agent-sdk-through-a-gateway-routing-budgets-mcp-bifrost-1920x1080.png --- Try Bifrost Enterprise free for 14 days. [Request access](https://www.getmaxim.ai/#enterprise-trial) **TL;DR** - The Claude Agent SDK runs the Claude Code engine as a library, and it reads `ANTHROPIC_BASE_URL` from its environment, so pointing it at an AI gateway takes one option. - Through Bifrost, Agent SDK model calls can fail over between Claude on the Anthropic API, AWS Bedrock, Google Vertex AI, and Azure without code changes. - The SDK's `max_budget_usd` caps one query using a client-side estimate; gateway budgets enforce per-tenant, per-team, and per-customer limits across every run. - Registering Bifrost as one HTTP MCP server gives the agent a filtered, audited tool catalog instead of credentials for every MCP server. - Bifrost adds 11 microseconds of overhead per request at 5,000 RPS, which is negligible next to provider response times in an agent loop. The Claude Agent SDK is Anthropic's Python and TypeScript library for building production agents on the same tools, agent loop, and context management that power Claude Code. Teams that move from prototypes to multi-tenant services quickly need three things the SDK does not provide on its own: routing and failover across Claude providers, spend limits that hold across runs and tenants, and controlled access to MCP tools. [Bifrost](https://www.getmaxim.ai/bifrost), the [open-source AI gateway for agent workloads](https://github.com/maximhq/bifrost), adds all three by sitting on the path of every model call and tool call the Claude Agent SDK makes. This guide walks through the setup and the routing, budget, and MCP configuration. ## What Is the Claude Agent SDK? The Claude Agent SDK is a library that embeds Claude Code's agent in your own Python or TypeScript application, providing built-in tools, the agent loop, permissions, hooks, subagents, sessions, and MCP support. It runs the Claude Code binary as a subprocess, so it inherits Claude Code's configuration model and environment variables. Anthropic's [Agent SDK overview](https://code.claude.com/docs/en/agent-sdk/overview) positions it between the Claude Code CLI (interactive use) and the client SDKs (raw API calls with your own loop). Capabilities that carry over from Claude Code include: - **Built-in tools:** reading and editing files, running commands, and web search - **Hooks and permissions:** custom callbacks around tool calls, and rules for which tools run automatically - **Subagents:** specialized agents for focused subtasks, with depth, concurrency, and spend caps - **MCP:** external tools over stdio, HTTP, or SSE, plus in-process SDK MCP servers - **Sessions:** resume and fork earlier work Anthropic's terms for the SDK also matter for architecture: third-party products built on it should use API key authentication rather than [claude.ai](http://claude.ai) login. That makes a gateway credential the natural fit for production services. The [Claude Code gateway explainer on routing, governance, and cost control](https://www.getmaxim.ai/articles/claude-code-gateway-explained-routing-governance-and-cost-control/) covers the same engine from the CLI side. ## Why Run the Claude Agent SDK Through a Gateway? Running the Claude Agent SDK through a gateway moves provider credentials, routing, budgets, and tool access out of agent code and into one governed layer. Agents make many model calls per task, often unattended, so these controls need to hold even when no human is watching the loop. Specific problems a gateway solves for Agent SDK services: - **Credential exposure:** the SDK reads its provider key from the environment of the agent process; Anthropic's hosting guidance recommends routing model calls through a proxy that injects the key outside the container instead - **Provider outages and rate limits:** a single provider endpoint means a 429 or 5xx stalls every running agent - **Unbounded spend:** loops and subagents multiply calls, and per-query caps do not limit a tenant's monthly total - **Tool sprawl:** each MCP server configured in agent code carries its own credentials and its own blast radius - **Fragmented visibility:** cost and usage live in each service's own logs Anthropic's own [Agent SDK configuration guide](https://code.claude.com/docs/en/agent-sdk/configuration) uses `ANTHROPIC_BASE_URL` pointed at a gateway as its example of setting environment variables. The same pattern underpins [governing AI agents in production](https://www.getmaxim.ai/articles/how-enterprises-govern-ai-agents-in-production/) more broadly. ## How to Connect the Claude Agent SDK to Bifrost Connecting the Claude Agent SDK to Bifrost takes two values passed through the SDK's `env` option: `ANTHROPIC_BASE_URL` set to the Bifrost `/anthropic` endpoint, and a Bifrost virtual key as the credential. Every model call from the agent loop and its subagents then flows through the gateway. ![](https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/2026/10/image-13.png) *Figure 1: Two settings, the base URL and one MCP server entry, put every model call and every tool call from the agent on a governed path.* Python: ```python import asyncio import os from claude_agent_sdk import query, ClaudeAgentOptions options = ClaudeAgentOptions( env={ "ANTHROPIC_BASE_URL": "", "ANTHROPIC_AUTH_TOKEN": os.environ["BIFROST_VIRTUAL_KEY"], }, model="claude-sonnet-4-6", ) async def main(): async for message in query(prompt="Triage the failing tests", options=options): print(message) asyncio.run(main()) ``` TypeScript: ```tsx import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Triage the failing tests", options: { env: { ...process.env, ANTHROPIC_BASE_URL: "", ANTHROPIC_AUTH_TOKEN: process.env.BIFROST_VIRTUAL_KEY!, }, model: "claude-sonnet-4-6", }, })) { console.log(message); } ``` Two details from the SDK's own documentation: in TypeScript, `env` replaces the subprocess environment, so spread `process.env` to keep `PATH` and other variables; in Python, `env` merges over the inherited environment. Claude Code sends `ANTHROPIC_AUTH_TOKEN` as a bearer token, which Bifrost accepts as a [virtual key](https://docs.getbifrost.ai/features/governance/virtual-keys). The [Bifrost Anthropic SDK integration](https://docs.getbifrost.ai/integrations/anthropic-sdk/overview) and the [Claude Code integration guide](https://docs.getbifrost.ai/cli-agents/claude-code) document the endpoint, accepted headers, and troubleshooting codes (a `403` usually means the key does not allow that model). ## Routing Claude Agent SDK Traffic Across Providers Bifrost routes Claude Agent SDK traffic by model name and virtual key configuration: the same agent can call Claude on the Anthropic API, AWS Bedrock, Google Vertex AI, or Azure, with weighted distribution across keys and automatic failover when a provider returns errors. The agent code does not change. ![](https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/2026/10/image-14.png) *Figure 2: The agent loop sees one successful response; retries, key rotation, and provider failover happen inside the gateway.* | Routing goal | Bifrost mechanism | Agent SDK change | | --- | --- | --- | | Use Claude on Bedrock or Vertex AI | Provider-prefixed model, such as `bedrock/...` or `vertex/...` | Set `model` | | Survive provider outages | [Automatic fallbacks](https://docs.getbifrost.ai/features/retries-and-fallbacks) with retries per provider | None | | Spread load across API keys | Weighted key distribution on the virtual key | None | | Keep a session on one provider's prompt cache | [Session affinity](https://docs.getbifrost.ai/providers/session-affinity) by session ID | Optional `x-bf-session-id` header | | Swap models without redeploying | [Routing rules](https://docs.getbifrost.ai/providers/routing-rules) and model aliases | None | Transient 5xx and network errors are retried on the same key with backoff, per-key failures such as a `429` rotate to another key, and fallbacks move to the next provider in the chain after retries are exhausted. Session affinity keeps a multi-turn agent run on the provider and key that served it, so it keeps hitting the same prompt cache; Claude Code subagents send their parent's session ID, so parallel subagents stay together. Anthropic documents that it does not support routing Claude Code to non-Claude models through any gateway. Bifrost can technically send Agent SDK traffic to other providers' models, but Claude-specific server tools may be missing, so production agents should keep Claude-family models and use the gateway for routing across Claude providers. The guide to [keeping your app running when Anthropic goes down](https://www.getmaxim.ai/articles/keep-your-app-running-when-anthropic-goes-down/) shows a full failover configuration. ## Budgets for Claude Agent SDK Runs Claude Agent SDK budgets work at two levels. The SDK's `max_budget_usd` caps the estimated spend of a single query, including subagents; Bifrost budgets cap spend per virtual key, team, and customer over a reset period, checked on every model call. Production services need both. ![](https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/2026/10/image-15.png) *Figure 3: The SDK cap stops one runaway query; gateway budgets stop a tenant, team, or customer from exceeding its period limit across every run.* Anthropic's [Agent SDK cost tracking guide](https://code.claude.com/docs/en/agent-sdk/cost-tracking) is explicit that `total_cost_usd` is a client-side estimate computed from a bundled price table and should not be used to bill end users. Gateway budgets fill that gap: - **Per-tenant keys:** issue one virtual key per tenant or agent service, each with its own budget and rate limit - **Hierarchy:** [Bifrost budgets and limits](https://docs.getbifrost.ai/features/governance/budget-and-limits) apply at the virtual key, team, and customer levels, and a request proceeds only if every applicable budget has room - **Calendar alignment:** budgets can reset on UTC day, week, month, quarter, or year boundaries to match billing periods - **Token and request limits:** rate limits cap tokens and requests per window, which bounds runaway loops independently of cost When a budget is exhausted, Bifrost rejects the request before it reaches a provider, and the agent receives an error it can handle. The architecture for [budgets and rate limits on multi-tenant LLM platforms](https://www.getmaxim.ai/articles/budget-and-rate-limit-architecture-for-multi-tenant-llm-platforms/) covers per-tenant design in depth. ## Governing MCP Tools for the Claude Agent SDK Governing MCP tools for the Claude Agent SDK means registering Bifrost as the agent's MCP server instead of each upstream server. Bifrost aggregates connected MCP servers behind one `/mcp` endpoint, filters the tools each virtual key can see, handles upstream authentication, and logs every tool call. Register Bifrost in `mcp_servers` with the virtual key in the `Authorization` header: ```python options = ClaudeAgentOptions( mcp_servers={ "bifrost": { "type": "http", "url": "", "headers": {"Authorization": f"Bearer {os.environ['BIFROST_VIRTUAL_KEY']}"}, } }, allowed_tools=["mcp__bifrost__*"], ) ``` What the gateway adds over configuring servers directly: - **Per-key tool filtering:** a virtual key's `mcp_configs` allow-list decides which servers and tools the agent sees; a key with no entry for a server exposes none of its tools unless that server is marked Allow by Default, as described in [MCP tool filtering](https://docs.getbifrost.ai/mcp/filtering) - **Central credentials:** upstream MCP servers authenticate at the gateway, with [MCP authentication](https://docs.getbifrost.ai/mcp/auth/overview) modes including OAuth 2.0 and per-user credentials, so agent containers hold no tool secrets - **Token efficiency:** [Code Mode](https://docs.getbifrost.ai/mcp/code-mode) exposes large tool catalogs through four meta-tools, cutting input tokens by up to 92.8% in published benchmarks at around 500 tools - **Enterprise controls:** [Bifrost guardrails](https://docs.getbifrost.ai/enterprise/guardrails) validate MCP tool executions as well as LLM traffic Tool approval stays with the agent: in gateway mode, Bifrost serves tools over MCP and the SDK's `allowed_tools`, permission rules, and hooks still decide what runs. The [Bifrost MCP gateway resource page](https://www.getmaxim.ai/bifrost/resources/mcp-gateway) and the article on [code execution with MCP and Code Mode token savings](https://www.getmaxim.ai/articles/code-execution-with-mcp-how-code-mode-cuts-agent-token-costs-by-90/) cover the tool side further. ## Attributing and Observing Agent SDK Runs Bifrost attributes every Agent SDK request to the virtual key or user that made it and records tokens, cost, latency, provider, and model per call. Adding a session or project header groups calls by agent run or initiative, which turns per-request logs into cost per task. The SDK passes extra headers through Claude Code's `ANTHROPIC_CUSTOM_HEADERS` variable (newline-separated `Name: Value` pairs), set in the same `env` option: ```python env={ "ANTHROPIC_BASE_URL": "", "ANTHROPIC_AUTH_TOKEN": os.environ["BIFROST_VIRTUAL_KEY"], "ANTHROPIC_CUSTOM_HEADERS": "x-bf-session-id: run-4821\nx-bf-lh-tenant: acme", } ``` - **Run grouping:** `x-bf-session-id` groups every call in an agent run, and the logs view reports session totals for cost and tokens - **Custom labels:** any `x-bf-lh-*` header is copied into log metadata, such as tenant, workflow, or environment - **Exports:** [built-in observability](https://docs.getbifrost.ai/features/observability/default) supports filtering and API access, Bifrost exports traces over OpenTelemetry, and Bifrost Enterprise streams one row per request to BigQuery For governance across many tenants, [virtual keys for platform teams governing LLM access](https://www.getmaxim.ai/articles/virtual-keys-explained-how-platform-teams-govern-llm-access-across-100-engineers/) explains how to structure keys per service. ## Production Checklist for Agent SDK Services A production Claude Agent SDK service routed through a gateway should keep provider keys out of the agent container, cap spend at both the query and tenant levels, expose only approved tools, and make every run attributable. The checklist below maps each requirement to its setting. | Requirement | Where to configure | Setting | | --- | --- | --- | | No provider key in the container | Bifrost | Provider keys stored in the gateway; agent holds a virtual key | | Claude provider failover | Bifrost | Fallback chain on Anthropic, Bedrock, Vertex AI | | Per-query spend cap | Agent SDK | `max_budget_usd` / `maxBudgetUsd` | | Per-tenant monthly budget | Bifrost | Virtual key budget, calendar-aligned | | Approved tools only | Bifrost and SDK | Virtual key `mcp_configs` plus `allowed_tools` | | Local action safety | Agent SDK | Hooks and permission rules | | Run-level attribution | Agent SDK env | `x-bf-session-id` via `ANTHROPIC_CUSTOM_HEADERS` | For regulated environments, [Bifrost Enterprise](https://www.getmaxim.ai/bifrost/enterprise) adds SSO-based identity, [in-VPC deployment](https://docs.getbifrost.ai/enterprise/invpc-deployments), and clustering. The walkthrough on [building production-ready AI agents with Bifrost as an MCP gateway](https://www.getmaxim.ai/articles/building-production-ready-ai-agents-with-bifrosts-mcp-gateway/) shows a complete agent build on the same stack. Bifrost adds 11 microseconds of overhead per request at 5,000 RPS in [published benchmarks](https://www.getmaxim.ai/bifrost/resources/benchmarks). ## Frequently Asked Questions ### What is the Claude Agent SDK? The Claude Agent SDK is Anthropic's Python and TypeScript library for building agents with the same tools, agent loop, and context management that power Claude Code. It provides built-in file, shell, and web tools, hooks, permissions, subagents, sessions, and MCP support, and it runs the Claude Code binary as a subprocess inside your application. ### Can I use the Claude Agent SDK with other models? Technically, a gateway can route Agent SDK requests to other providers' models, but Anthropic does not support routing Claude Code, which the SDK runs, to non-Claude models. Claude-specific server tools may not work elsewhere. The supported path is Claude-family models on the Anthropic API, AWS Bedrock, Google Vertex AI, or Azure, with a gateway handling failover between them. ### How do I set a custom base URL for the Claude Agent SDK? Pass `ANTHROPIC_BASE_URL` through the SDK's `env` option, or set it in the environment of the process running the agent. For Bifrost, use the `/anthropic` endpoint, such as `https://bifrost.example.com/anthropic`, and pass a Bifrost virtual key as `ANTHROPIC_AUTH_TOKEN`. In TypeScript, spread `process.env` into `env`, because the option replaces the inherited environment. ### How do I limit how much a Claude Agent SDK agent spends? Use two limits. Set `max_budget_usd` in Python or `maxBudgetUsd` in TypeScript to cap a single query's estimated spend, including subagents. Then enforce period budgets per tenant, team, or customer at the gateway, which checks every model call and blocks requests once any applicable budget is exhausted. ### How does the Claude Agent SDK connect to MCP servers? The Agent SDK connects to MCP servers through the `mcp_servers` option, using stdio, HTTP, or SSE transports, or in-process SDK servers. Tools appear as `mcp____` and must be permitted through `allowed_tools` or permission rules. Registering a single MCP gateway as an HTTP server gives the agent a filtered catalog with centrally managed credentials, the same pattern used to [connect Claude Code to an MCP gateway](https://www.getmaxim.ai/articles/how-to-connect-claude-code-to-an-mcp-gateway/). ### Is the Claude Agent SDK open source? The Python and TypeScript Agent SDK packages are published on GitHub, and Anthropic states that use of the SDK is governed by its Commercial Terms of Service, except where a component carries its own license. The SDK runs the Claude Code binary, so review the license file of each component before redistributing it in a product. ## Run the Claude Agent SDK on Bifrost The Claude Agent SDK gives teams a production agent loop; the Bifrost AI gateway gives that loop routing across Claude providers, budgets that hold across tenants, and a governed MCP tool catalog. Pointing `ANTHROPIC_BASE_URL` and one MCP server entry at [Bifrost](https://www.getmaxim.ai/bifrost) is the whole integration. To see Claude Agent SDK services running on a governed gateway, [book a demo with the Bifrost team](https://getmaxim.ai/bifrost/book-a-demo). ## Read next [![OpenAI Responses API vs Chat Completions vs Anthropic Messages](https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w720/2026/10/openai-responses-api-vs-chat-completions-vs-anthropic-messag-bifrost-1920x1080.png) The OpenAI Responses API is OpenAI's stateful, item-based interface for agentic apps, while Chat Completions and Anthropic Messages remain stateless message APIs. This guide compares the three on state, tools, reasoning, and retention, and shows how Bifrost serves all three formats.](https://www.getmaxim.ai/articles/openai-responses-api-vs-chat-completions-vs-anthropic-messages/) [![FinOps for AI: Showback and Chargeback for LLM Spend](https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w720/2026/10/finops-for-ai-showback-and-chargeback-for-llm-spend-bifrost-1920x1080.png) FinOps for AI is the practice of making LLM and agent spend visible, attributable, and accountable to the teams that create it. This guide explains showback vs chargeback for AI, the attribution model AI spend needs, and how to build both from request-level data at the AI gateway.](https://www.getmaxim.ai/articles/finops-for-ai-showback-and-chargeback-for-llm-spend/) [![OpenClaw vs Hermes: Which Agent to Run and How to Control It](https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w720/2026/10/openclaw-vs-hermes-which-agent-to-run-and-how-to-control-it-bifrost-1920x1080.png) OpenClaw and Hermes Agent are open-source, self-hosted AI agents that run on your own hardware and reach you through chat apps. This openclaw vs hermes guide compares how each is built and secured, says which to run for which job, and shows how to cap its models, spend, and MCP tools.](https://www.getmaxim.ai/articles/openclaw-vs-hermes-which-agent-to-run-and-how-to-control-it/) ## More in AI Gateway [![OpenAI Responses API vs Chat Completions vs Anthropic Messages](https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w720/2026/10/openai-responses-api-vs-chat-completions-vs-anthropic-messag-bifrost-1920x1080.png) The OpenAI Responses API is OpenAI's stateful, item-based interface for agentic apps, while Chat Completions and Anthropic Messages remain stateless message APIs. This guide compares the three on state, tools, reasoning, and retention, and shows how Bifrost serves all three formats.](https://www.getmaxim.ai/articles/openai-responses-api-vs-chat-completions-vs-anthropic-messages/) ```json { "@context": "https://schema.org", "@type": "Article", "publisher": { "@type": "Organization", "name": "Maxim Articles", "url": "https://www.getmaxim.ai/articles/", "logo": { "@type": "ImageObject", "url": "https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w256h256/2025/08/thumbnail.png", "width": 60, "height": 60 } }, "author": { "@type": "Person", "name": "Kamya Shah", "image": { "@type": "ImageObject", "url": "https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/2025/09/WhatsApp-Image-2025-08-29-at-17.40.40-1.jpeg", "width": 1200, "height": 1600 }, "url": "https://www.getmaxim.ai/articles/author/kamya/", "sameAs": [] }, "headline": "Claude Agent SDK Through a Gateway: Routing, Budgets, MCP", "url": "https://www.getmaxim.ai/articles/claude-agent-sdk-through-a-gateway-routing-budgets-mcp/", "datePublished": "2026-10-22T20:28:47.000Z", "dateModified": "2026-10-22T20:28:47.000Z", "image": { "@type": "ImageObject", "url": "https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w1200/2026/10/claude-agent-sdk-through-a-gateway-routing-budgets-mcp-bifrost-1920x1080.png", "width": 1200, "height": 675 }, "keywords": "AI Gateway", "description": " The Claude Agent SDK packages Claude Code's agent loop, tools, and context management as a Python and TypeScript library. This guide shows how to route Claude Agent SDK traffic through Bifrost for provider routing and failover, per-tenant budgets, and governed MCP tool access.\n", "mainEntityOfPage": "https://www.getmaxim.ai/articles/claude-agent-sdk-through-a-gateway-routing-budgets-mcp/" } ```