Bring Your Own API Key (BYOK) for MCP Tools — How It Works

What Is BYOK?

Bring Your Own Key means exactly what it says. You hand the gateway an API key you already own for a specific provider — OpenAI, Stripe, Twilio, Resend, Tavily, or any supported service — and every call to that provider flows through your key instead of the gateway's shared pool.

Without BYOK, an MCP gateway executes tool calls using its own upstream credentials and charges you credits for each call. That model works well when you do not have a provider account or when you want unified billing across dozens of tools. But if you already have a negotiated rate with OpenAI or a high-volume Twilio plan, paying credits on top of your existing subscription means double-paying for the same API access.

BYOK eliminates that. You keep your existing provider relationship, your existing rate, and your existing usage dashboard. The gateway still handles routing, protocol translation, and response normalization — it just authenticates with your key instead of its own.

How BYOK Works in an MCP Gateway

The flow is straightforward:

1. You register a provider key via the BYOK endpoint, specifying which provider it belongs to.
2. The gateway encrypts the key at rest and associates it with your account.
3. When you execute a tool call that hits that provider, the gateway checks whether you have a BYOK key registered for it.
4. If a BYOK key exists, the gateway uses it. No credits are deducted. The provider bills you directly at your rate.
5. If no BYOK key exists, the gateway falls back to its shared key and deducts credits from your balance.

This means you can mix and match. Use BYOK for providers where you have a volume discount, and credits for everything else. The gateway resolves the correct authentication path on every call.

Registering a BYOK Key

Register a key by sending a POST request to /api/v1/byok with your ToolRoute session and the provider details.

# Register your OpenAI key
curl -X POST https://toolroute.ai/api/v1/byok \
  -H "Authorization: Bearer tr_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "api_key": "sk-proj-your-openai-key..."
  }'

# Response
{
  "id": "byok_7f3a...",
  "provider": "openai",
  "status": "active",
  "created_at": "2026-04-16T12:00:00Z"
}

You can register keys for multiple providers. Each registration is scoped to one provider. If you need to rotate a key, register a new one for the same provider and the old one is replaced.

# Register keys for multiple providers
curl -X POST https://toolroute.ai/api/v1/byok \
  -H "Authorization: Bearer tr_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "provider": "stripe", "api_key": "sk_live_your-stripe-key..." }'

curl -X POST https://toolroute.ai/api/v1/byok \
  -H "Authorization: Bearer tr_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "provider": "twilio", "api_key": "your-twilio-sid:your-auth-token" }'

Making Calls With BYOK

Once a key is registered, you do not change anything about how you call tools. The execute endpoint is identical whether the gateway uses your key or its own.

# This call uses your OpenAI key automatically (BYOK registered)
curl -X POST https://toolroute.ai/api/v1/execute \
  -H "Authorization: Bearer tr_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "openai",
    "operation": "chat_completion",
    "input": {
      "model": "gpt-4o",
      "messages": [
        { "role": "user", "content": "Summarize this document." }
      ]
    }
  }'

# Response includes billing_mode so you know what happened
{
  "result": { "choices": [...] },
  "billing": {
    "mode": "byok",
    "credits_charged": 0,
    "provider": "openai"
  }
}

The response includes a billing object so your agent or application can confirm whether the call used BYOK or credits. This is useful for cost tracking and for verifying that your key registration is active.

Checking Which Tools Use BYOK vs Credits

The key info endpoint shows your registered BYOK providers alongside your credit balance, so you always know which tools bill to your provider account and which deduct from credits.

# Check your key info, balance, and BYOK registrations
curl https://toolroute.ai/api/v1/key \
  -H "Authorization: Bearer tr_live_abc123..."

{
  "key_id": "key_9x2b...",
  "credits_remaining": 42.50,
  "byok_providers": [
    { "provider": "openai", "status": "active", "registered": "2026-04-16" },
    { "provider": "stripe", "status": "active", "registered": "2026-04-16" },
    { "provider": "twilio", "status": "active", "registered": "2026-04-16" }
  ],
  "credit_providers": [
    "tavily", "resend", "firecrawl", "exa", "browserbase"
  ]
}

The byok_providers array lists every provider where your key is registered. The credit_providers array lists providers that will deduct from your credit balance. Free tools (Context7, Playwright, Semgrep) appear in neither list because they cost nothing either way.

When to Use BYOK vs Credits

The optimal setup for most teams: BYOK for the two or three providers you use heavily (often OpenAI and one communication tool), and prepaid credits for everything else. This gives you the best rate where it matters and zero-friction access to the long tail of tools you use occasionally.

Security: How BYOK Keys Are Handled

Handing your API keys to a third party requires trust. Here is how ToolRoute handles BYOK credentials:

• Encrypted at rest. Every BYOK key is encrypted using AES-256-GCM before it touches the database. The encryption key is stored separately from the data.
• Never logged. API keys do not appear in request logs, error logs, or analytics. The gateway decrypts the key in-memory for the duration of the upstream call, then discards it.
• Never exposed in responses. The BYOK registration endpoint returns a reference ID, not the key itself. No API response ever includes your provider key.
• Scoped to one provider. Each BYOK registration is locked to a single provider. The key is only decrypted when the gateway routes a call to that specific provider.
• Deletable at any time. Send a DELETE request to revoke a BYOK registration. The encrypted key is purged, and future calls fall back to credits.

# Revoke a BYOK key — calls fall back to credits immediately
curl -X DELETE https://toolroute.ai/api/v1/byok/byok_7f3a... \
  -H "Authorization: Bearer tr_live_abc123..."

For additional details on how the gateway handles upstream credentials and request isolation, see the MCP server security best practices guide.

BYOK Through the MCP Protocol

If you connect to ToolRoute as an MCP server (for example, from Claude Code or another MCP client), BYOK works identically. The gateway checks for registered keys on every tool call regardless of which protocol delivered the request — REST, MCP Streamable HTTP, A2A, or OpenAI function calling.

// .mcp.json — connect to ToolRoute as an MCP server
// BYOK keys you registered apply automatically to all calls
{
  "toolroute": {
    "type": "http",
    "url": "https://toolroute.ai/mcp",
    "headers": {
      "Authorization": "Bearer tr_live_abc123..."
    }
  }
}

Your agent calls OpenAI through the MCP interface. The gateway sees you have a BYOK key for OpenAI, uses it, returns the result, and charges zero credits. The agent does not need to know whether BYOK or credits funded the call.

Common Questions

What happens if my BYOK key is invalid or expired?

The gateway attempts the call with your key. If the upstream provider returns an authentication error, the gateway returns that error to you — it does not silently fall back to credits. This prevents unexpected charges. You will see a clear error message indicating the BYOK key was rejected by the provider.

Can I use BYOK for some operations and credits for others on the same provider?

BYOK is registered at the provider level, not the operation level. If you register an OpenAI key, all OpenAI operations use it. If you want credit-based billing for a provider, do not register a BYOK key for it.

Is there a cost to use BYOK?

No. BYOK calls do not deduct credits. You pay only whatever the upstream provider charges for the API call. The gateway does not add a surcharge on BYOK requests. See pricing for the full breakdown of free tools, credit costs, and BYOK eligibility per provider.

Which providers support BYOK?

Any provider where the gateway uses an API key for upstream authentication supports BYOK. This includes OpenAI, Stripe, Twilio, Resend, Tavily, Firecrawl, ElevenLabs, Exa, and others. The full list is available in the documentation. Free tools that do not require upstream keys (Context7, Playwright, Semgrep) do not need BYOK because they are already free.