Skip to main content

Using API Keys

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

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 bundle deployments and tool updates
  • Scripts and automation - Programmatically manage bundles 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 the Bundle 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 a bundle's MCP endpoint
curl -X POST https://mcp.mcpbundles.com/bundle/your-bundle-slug \
  -H "X-API-Key: ${MCPBUNDLES_API_KEY}" \
  -H "Content-Type: application/json"

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​

All API requests must include the API key in the X-API-Key header:

X-API-Key: ${MCPBUNDLES_API_KEY}

Replace ${MCPBUNDLES_API_KEY} with your actual API key value.

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 was created by a different user

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?​