Claude Agent SDK Through a Gateway: Routing, Budgets, MCP

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, the open-source AI gateway for agent workloads, 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 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 login. That makes a gateway credential the natural fit for production services. The Claude Code gateway explainer on 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 uses ANTHROPIC_BASE_URL pointed at a gateway as its example of setting environment variables. The same pattern underpins governing 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.

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:

import asyncio
import os
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    env={
        "ANTHROPIC_BASE_URL": "<https://bifrost.example.com/anthropic>",
        "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:

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: "<https://bifrost.example.com/anthropic>",
      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. The Bifrost Anthropic SDK integration and the Claude Code integration guide 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.

Figure 2: The agent loop sees one successful response; retries, key rotation, and provider failover happen inside the gateway.

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 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.

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 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 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 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:

options = ClaudeAgentOptions(
    mcp_servers={
        "bifrost": {
            "type": "http",
            "url": "<https://bifrost.example.com/mcp>",
            "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
• Central credentials: upstream MCP servers authenticate at the gateway, with MCP authentication modes including OAuth 2.0 and per-user credentials, so agent containers hold no tool secrets
• Token efficiency: 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 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 and the article on code execution with MCP and Code Mode token savings 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:

env={
    "ANTHROPIC_BASE_URL": "<https://bifrost.example.com/anthropic>",
    "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 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 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.

For regulated environments, Bifrost Enterprise adds SSO-based identity, in-VPC deployment, and clustering.

The walkthrough on building production-ready AI agents with Bifrost as an 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.

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__<server>__<tool> 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.

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 is the whole integration. To see Claude Agent SDK services running on a governed gateway, book a demo with the Bifrost team.