For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dashboard
User GuideDeveloper GuidesAPI Reference
User GuideDeveloper GuidesAPI Reference
  • Getting Started
    • What is Runtype?
    • Creating your account
    • Platform Keys vs. BYOK
    • Understanding the Runtype UI
    • Quickstart: Social Media Post Generator
    • Quickstart: From Agent to Chat Widget
  • Dashboard
    • What is the Dashboard?
    • Daily Executions
  • Playground
    • What is the Playground?
  • Products & Surfaces
    • What are Products?
    • What are Surfaces?
    • Creating a Product
    • Setting up a Chat Surface
    • Setting up an API Surface
    • Setting up an MCP Surface
    • Setting up an A2A Surface
    • Setting up a Slack Surface
    • MCP authentication
    • Authenticating with product API keys
    • Embedding the chat widget (script tag)
    • Embedding the chat widget (React)
    • Surface orchestration modes
    • Product views
    • Adding Capabilities to a product
    • Connecting external agents
    • How A2A works
    • Connecting to Cursor / VS Code
    • Connecting to Claude Desktop
    • Scoping API keys to capabilities
    • Auto-generated OpenAPI spec
    • Calling your API endpoints
    • Client tokens and domain restrictions
    • AI-powered theme generation
    • Widget theming and customization
    • Product versioning and status
  • Flows
    • What are Flows?
    • Creating and Editing Flows
    • Flow step types overview
    • Agent and Flow Templates
    • Using prompt steps
    • Using transform-data steps
    • Using conditional steps
    • Using fetch-url and api-call steps
    • Using record steps (upsert/retrieve)
    • Flow variables and templates
    • Flow versioning and publishing
    • Running flows in batch
    • Handling batch failures
    • Debugging flows
  • Agents
    • What are Agents?
    • Creating and configuring Agents
    • Agent tools
  • Records
    • What are Records?
    • Creating and managing records
    • Using records in flows
    • Filtering and searching records
  • Tools
    • What are Tools?
    • Built-in Tools
    • Creating custom tools
    • Creating external tools
    • Runtime tools
  • Evals
    • What are Evals?
    • Running an Eval
    • Interpreting eval results
  • Schedules
    • What are Schedules?
    • Automating batch processing
  • Logs
    • What are Logs?
    • Working with Logs
  • Integrations
    • Connecting AI model providers
    • Slack integration
    • Google Workspace integration
    • GitHub integration
    • Linear integration
    • Weaviate (vector search)
    • Firecrawl (web scraping)
    • Exa (web search)
  • Settings
    • What's in Settings?
    • Available AI models
    • What are Organizations?
    • Managing AI models
    • Managing API keys
    • Billing and plans
    • Usage data
    • Team members and permissions
    • Appearance and preferences
    • Integrations (PostHog, Weaviate, Daytona)
  • Troubleshooting & FAQ
    • FAQ
    • Rate Limits and Usage
    • Managing Runtype with Claude
    • Flow execution failures
    • Common errors and solutions
    • Authentication issues
Dashboard
LogoLogo
On this page
  • How MCP authentication works
  • Creating MCP-specific keys
  • Key security
  • Revoking MCP access
  • Authentication errors
  • Next steps
Products & Surfaces

MCP authentication

Was this page helpful?
Previous

Authenticating with product API keys

Next
Built with

MCP surfaces use API keys for authentication. Secure your MCP connections by properly managing keys and understanding authentication Flows.

How MCP authentication works

MCP Surfaces support two authentication modes:

  • OAuth — The AI IDE connects to your MCP server URL directly. On first connection, the user authorizes via a browser-based OAuth flow. This is the recommended mode for Claude Desktop and Cursor.
  • API Key — The IDE passes an API key (with the mcp_ prefix) as a Bearer token in each request. Use this for clients that do not support OAuth.

Authentication flow with API keys:

  1. IDE connects to the MCP server URL with the API key
  2. Runtype validates the key on each request
  3. AI assistant discovers available tools
  4. When invoking a tool, the IDE includes the API key in the request
  5. Runtype validates the key and executes the Capability

Creating MCP-specific keys

Create dedicated API keys for MCP to isolate access:

  1. Go to your MCP Surface
  2. Open the Keys tab
  3. Click Generate API Key
  4. Name it descriptively, such as “MCP - Claude Desktop”
  5. Click Generate
  6. Copy the key immediately. Production keys cannot be recovered after creation.

MCP Surface keys use the mcp_ prefix. Use separate keys for each IDE or team member so you can revoke access without disrupting other users.

Key security

When using API key authentication, keys are stored in plain text in IDE configuration files. Protect them:

  • Don’t commit to version control — Add IDE config files to .gitignore
  • Use environment-specific keys — Development keys for local IDEs, production keys only when necessary
  • Rotate regularly — Generate new keys periodically

Revoking MCP access

If a key is compromised or no longer needed:

  1. Go to your MCP Surface
  2. Open the Keys tab
  3. Find the key to revoke
  4. Click Revoke
  5. Confirm

The key stops working immediately. Update IDE configurations with a new key if continued access is needed.

Authentication errors

Common MCP authentication issues:

Invalid API key:

  • Key was revoked or deleted
  • Typo in configuration
  • Using development key with production surface

Permission denied:

  • Key is scoped to different capabilities
  • Surface status is Inactive

Check the IDE’s output panel for detailed error messages from the MCP server.

Next steps

  • Scoping API keys to capabilities for fine-grained access control
  • Connecting to Claude Desktop
  • Connecting to Cursor / VS Code