Skip to main content

Using API Keys

MCPBundles provides API keys for programmatic access to your MCP servers and tools. Use them to authenticate with the GraphQL API and MCP endpoints from scripts, CI/CD pipelines, remote cloud agents, and other automated systems.

Two layers of authentication​

Connecting an MCP server often involves two separate auth steps:

  1. Service credentials — OAuth or API keys for the upstream product (QuickBooks, HubSpot, Gmail, etc.). Connect these once in the MCPBundles dashboard. MCPBundles stores them encrypted and attaches them when tools run.
  2. MCPBundles platform auth — your workspace API key on every MCP HTTP request so MCPBundles knows which workspace (and stored service credentials) to use.

Completing service OAuth in the dashboard does not replace platform auth for remote or headless clients. A remote agent still needs your workspace API key in a request header even when QuickBooks (or another provider) is already connected.

See Setting Up Credentials for service credentials.

Types of API Keys​

Workspace API Keys​

Workspace API keys are scoped to a specific workspace and execute as your user account within that workspace. They're perfect for:

  • CI/CD pipelines - Automate MCP server deployments and tool updates
  • Scripts and automation - Programmatically manage MCP servers and credentials
  • Third-party integrations - Connect external tools to your MCPBundles workspace

AI API Keys​

AI API keys are used to authenticate with AI providers (like Anthropic) when using MCPBundles Studio. These keys allow you to use your own AI provider credits instead of platform credits.

Creating a Workspace API Key​

  1. Navigate to your workspace settings
  2. Go to the Workspace API Keys section
  3. Click Create API Key
  4. Give it a descriptive name (e.g., "CI/CD Pipeline", "Local Development")
  5. Optionally set an expiration time
  6. Copy the key immediately - it's only shown once
warning

API keys are like passwords. Store them securely and never commit them to version control.

Using API Keys​

GraphQL API​

Authenticate GraphQL requests using the X-API-Key header:

curl -X POST https://api.mcpbundles.com/graphql \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${MCPBUNDLES_API_KEY}" \
  -d '{
    "query": "{ me { id email } }"
  }'

MCP Endpoints​

When connecting to MCP endpoints, include the API key in the connection headers:

# Example: Connect to an MCP server endpoint
curl -X POST https://mcp.mcpbundles.com/bundle/your-bundle-slug \
  -H "X-API-Key: ${MCPBUNDLES_API_KEY}" \
  -H "Content-Type: application/json"

Remote and headless MCP clients​

Use a workspace API key when the MCP client cannot complete interactive sign-in on each run:

  • Claude Code Routines — Anthropic's cloud-hosted scheduled or API-triggered jobs (Routines documentation)
  • CI/CD pipelines and server-side scripts
  • curl or custom HTTP clients testing MCP endpoints

Workflow:

  1. Connect service credentials (OAuth, provider API keys) in the MCPBundles dashboard.
  2. Create a workspace API key (below).
  3. Configure the remote client to send that key on every MCP HTTP request using a header (see MCP URL and header rules).

For Claude Code Routines specifically, see Claude Code MCP Setup — Routines section.

MCP URL and header rules​

The generic MCP server URL is the same for every user in your workspace:

https://mcp.mcpbundles.com/bundle/{slug}

Example: https://mcp.mcpbundles.com/bundle/quickbooks

  • No user-specific MCP URL — the slug identifies the MCP server, not your account.
  • Do not embed tokens in the URL — MCPBundles does not support ?token= query parameters or other secrets in the URL path.
  • Pass your workspace API key in a header on every MCP HTTP request:
X-API-Key: mb_YOUR_KEY

Also accepted:

Authorization: Api-Key mb_YOUR_KEY

When you curl an MCP endpoint, the response may list oauth2 and bearer auth schemes — that describes MCP protocol options. For headless and remote clients, use your workspace API key in a header, not a token appended to the URL.

Environment Variables​

Store your API key securely as an environment variable:

# .env file (never commit this!)
export MCPBUNDLES_API_KEY="your-api-key-here"
# Use in scripts
curl -H "X-API-Key: ${MCPBUNDLES_API_KEY}" ...

Code Examples​

Python:

import os
import requests

api_key = os.environ.get("MCPBUNDLES_API_KEY")
headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.mcpbundles.com/graphql",
    headers=headers,
    json={"query": "{ me { id email } }"}
)

JavaScript/Node.js:

const apiKey = process.env.MCPBUNDLES_API_KEY;

const response = await fetch('https://api.mcpbundles.com/graphql', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: '{ me { id email } }',
  }),
});

Go:

package main

import (
    "net/http"
    "os"
)

func main() {
    apiKey := os.Getenv("MCPBUNDLES_API_KEY")
    
    req, _ := http.NewRequest("POST", "https://api.mcpbundles.com/graphql", nil)
    req.Header.Set("X-API-Key", apiKey)
    req.Header.Set("Content-Type", "application/json")
    
    client := &http.Client{}
    client.Do(req)
}

Header Format​

Include your workspace API key in a request header — not in the URL.

Preferred:

X-API-Key: mb_YOUR_KEY

Also accepted:

Authorization: Api-Key mb_YOUR_KEY

Replace mb_YOUR_KEY with the key you copied when creating it. Keys start with mb_.

Workspace Scoping​

Workspace API keys are automatically scoped to the workspace they were created in. All requests made with a workspace API key will:

  • Only access resources in that workspace
  • Execute as the user who created the key
  • Respect workspace-level permissions and settings

Security Best Practices​

Key Management​

  • Rotate regularly - Update API keys periodically (every 90 days recommended)
  • Use descriptive names - Name keys after their purpose (e.g., "Production CI/CD", "Staging Deploy")
  • Set expiration dates - Use expiration times for temporary access
  • One key per service - Create separate keys for different services/environments

Storage​

  • Never commit keys - Add .env files to .gitignore
  • Use secret managers - Store keys in AWS Secrets Manager, HashiCorp Vault, or similar
  • Environment-specific - Use different keys for development, staging, and production
  • Restrict access - Only share keys with trusted team members

Monitoring​

  • Track usage - Monitor which keys are being used and when
  • Review regularly - Audit active keys and revoke unused ones
  • Watch for anomalies - Set up alerts for unusual API key activity

Rotating API Keys​

To rotate an API key:

  1. Create a new API key
  2. Update all systems using the old key
  3. Verify everything works with the new key
  4. Revoke the old key

This ensures zero downtime during rotation.

Revoking API Keys​

If an API key is compromised or no longer needed:

  1. Go to Workspace API Keys in settings
  2. Find the key you want to revoke
  3. Click the delete/trash icon
  4. Confirm the deletion

The key will be immediately invalidated and all requests using it will fail.

warning

Revoking an API key cannot be undone. Make sure you have a replacement key ready before revoking.

Troubleshooting​

"Invalid API Key" Error​

Possible causes:

  • Key was revoked or expired
  • Key copied incorrectly (extra spaces, missing characters)
  • Wrong header name (should be X-API-Key, not X-Api-Key)

Fix:

  1. Verify the key in your workspace settings
  2. Copy the key again (ensure no extra spaces)
  3. Check that you're using the exact header name: X-API-Key

"Unauthorized" Error​

Possible causes:

  • Key doesn't have permission for the requested resource
  • Key is scoped to a different workspace
  • Key doesn't exist in the current workspace (workspace API keys are personal — they don't transfer between workspaces)

Fix:

  1. Verify the key belongs to the correct workspace
  2. Check that the key creator has the necessary permissions
  3. Ensure you're making requests to the correct workspace endpoint

Key Not Found After Creation​

Cause: API keys are only shown once when created.

Fix:

  • If you lost the key, you must create a new one
  • The old key cannot be recovered
  • Consider setting up key rotation to avoid this issue

Rate Limits​

API keys are subject to the same rate limits as user authentication. Contact support for current rate limit information.

Next Steps​

Need Help?​