API Keys

MCP API keys provide simple, secure authentication for AI clients to connect to your n8n workflows through the MCP protocol.

What are MCP API Keys?

MCP API keys are credentials that allow AI assistants (like Claude Desktop) to authenticate with the n8n MCP Bridge server. Each key is associated with a specific n8n connection and provides access to that connection's workflows and resources.

Creating an API Key

Prerequisites

Before creating an API key:

1. You must have an n8n connection configured
2. The n8n connection must be tested and working
3. You must be signed in to the dashboard

Creation Process

1. Navigate to Dashboard

   • Go to http://localhost:3000/dashboard
   • Click the API Keys tab

2. Click "Create API Key"

   • A modal dialog will appear

3. Fill in Details

   • API Key Name: Descriptive name (e.g., "Claude Desktop - MacBook")
   • n8n Connection: Select from your configured connections

4. Create and Save

   • Click Create API Key
   • Copy the generated key immediately
   • Store it securely (you won't see it again!)

API Key Format

All MCP API keys follow this structure:

mcp_{random_characters}

• Prefix: Always starts with mcp_
• Length: 32+ characters total
• Characters: Lowercase letters and numbers
• Generation: Uses CUID2 for uniqueness

Example:

mcp_clph1234abcd5678efgh9012ijkl

Using API Keys

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "n8n": {
      "url": "http://localhost:3001/mcp?apiKey=mcp_your_key_here"
    }
  }
}

With MCP Inspector

Connect using the URL:

http://localhost:3001/mcp?apiKey=mcp_your_key_here

With Custom Clients

Include the API key as a query parameter in the MCP endpoint URL:

const mcpClient = new MCPClient({
  url: 'http://localhost:3001/mcp?apiKey=mcp_your_key_here',
})

Managing API Keys

View All Keys

In the API Keys tab, you can see:

• Name: Your descriptive name
• Connection: Associated n8n connection
• Status: Active or inactive
• Created: When the key was created
• Last Used: Last access timestamp
• Actions: Test, edit, delete

Test Connection

To verify an API key works:

1. Find the key in the table
2. Click Test Connection
3. Wait for the result:
   • ✓ "Connected" - Key is working
   • ✗ "Failed" - Connection issue

Edit API Key

You can update:

• API key name (for organization)
• Associated n8n connection
• Memory settings

Note: You cannot change the actual key value. To get a new key, create a new one and delete the old.

Delete (Revoke) API Key

To revoke an API key:

1. Click the trash icon next to the key
2. Confirm the deletion
3. The key is immediately invalidated

Warning: Any clients using this key will lose access.

Security Best Practices

Key Storage

• Never commit to version control (add *.json to .gitignore)
• Don't share via email or chat
• Use environment variables in CI/CD pipelines
• Store in secrets manager for production

Key Rotation

Rotate keys regularly:

1. Create a new API key
2. Update all clients with the new key
3. Verify clients are working
4. Delete the old key

Recommended rotation schedule:

• Development: Every 30 days
• Production: Every 90 days
• Immediately: If compromised

Access Control

• One key per device/client: Don't reuse keys
• Descriptive names: Know which key is where
• Monitor usage: Check "Last Used" regularly
• Revoke unused keys: Clean up old keys

Least Privilege

Each API key has access to:

• One n8n connection only
• Workflows in that connection
• Memory items for that key

Keys cannot:

• Access other users' data
• Modify n8n connection settings
• Create new keys
• Access admin functions

API Key Lifecycle

Creation

1. User creates key via dashboard
2. System generates unique key with mcp_ prefix
3. Key hash is stored in database
4. Full key is shown once to user

Active Use

1. Client sends request with API key
2. MCP server validates key via internal API
3. Next.js app checks key hash in database
4. If valid, request is processed
5. Usage is logged

Revocation

1. User deletes key via dashboard
2. Database record is removed
3. All future requests with this key fail
4. Existing sessions are terminated

Monitoring & Analytics

Usage Statistics

View API key usage in the dashboard:

• Total Calls: Number of MCP requests
• Last Used: Timestamp of last access
• Success Rate: Percentage of successful calls
• Error Count: Failed requests

Access Logs

Each API key request is logged:

{
  apiKeyId: "...",
  timestamp: "2024-01-15T10:30:00Z",
  method: "execute_workflow",
  success: true,
  duration: 1250 // milliseconds
}

View logs in the Usage tab.

Troubleshooting

"Invalid API Key" Error

If you see this error:

1. Check the key value

   • Ensure no extra spaces
   • Verify it starts with mcp_
   • Confirm you copied the full key

2. Verify key exists

   • Go to dashboard → API Keys
   • Check if the key is listed
   • If not, it may have been deleted

3. Test in dashboard

   • Click "Test Connection" for the key
   • If it fails, check n8n connection

"Connection Failed" Error

If the key is valid but connection fails:

1. Check n8n instance

   • Verify n8n is running
   • Test n8n URL in browser
   • Confirm n8n API key is valid

2. Check MCP server

   • Verify server is running on port 3001
   • Test: curl http://localhost:3001/health

3. Network issues

   • Check firewall settings
   • Verify no proxy interference
   • Ensure ports are open

Key Not Working After Creation

If a newly created key doesn't work:

1. Wait a moment - Database replication may take 1-2 seconds
2. Restart MCP server - May need to reload configuration
3. Recreate key - If issue persists, create a new one

Advanced Usage

Multiple API Keys

Use cases for multiple keys:

• Per device: Separate keys for each computer
• Per environment: Different keys for dev/staging/prod
• Per client: One for Claude, one for VS Code, etc.
• Per team member: Individual accountability

Environment-Specific Keys

Development configuration:

{
  "mcpServers": {
    "n8n-dev": {
      "url": "http://localhost:3001/mcp?apiKey=mcp_dev_key"
    }
  }
}

Production configuration:

{
  "mcpServers": {
    "n8n-prod": {
      "url": "https://mcp.example.com/mcp?apiKey=mcp_prod_key"
    }
  }
}

Programmatic Access

For automated systems:

import { MCPClient } from '@modelcontextprotocol/sdk'

const apiKey = process.env.MCP_API_KEY
const client = new MCPClient({
  url: `http://localhost:3001/mcp?apiKey=${apiKey}`,
})

Limits and Quotas

Current limitations:

• No rate limiting - Unlimited requests (for now)
• No expiration - Keys don't expire automatically
• No usage limits - No monthly/daily caps

Future features:

• Configurable rate limits
• Usage quotas
• Automatic expiration
• Cost tracking

Next Steps

• Set up OAuth Clients →
• Configure Memory System →
• View Usage Analytics →