Skip to main content

​
MCP Authentication

The Octolane MCP server supports API key authentication (recommended for personal use) and OAuth 2.0 (for building integrations that access other users’ workspaces).

​
API key authentication

The simplest way to connect. Use the same API key you’d use for the REST API.

​
Get your API key

  1. Go to your Octolane dashboard
  2. Navigate to Settings > Integrations > API
  3. Click Generate API key (or copy your existing one)

​
Use it in your MCP config

Pass the key in the X-API-Key header: 
{
  "mcpServers": {
    "octolane": {
      "url": "https://mcp.octolane.com/mcp",
      "headers": {
        "X-API-Key": "oct_live_abc123def456..."
      }
    }
  }
}
The API key identifies your workspace and gives full access to all MCP tools. One key per workspace.

​
OAuth 2.0

OAuth support for MCP is coming soon. If you’re building an integration that needs OAuth, email us at one@octolane.com and we’ll get you early access.
OAuth will allow third-party applications to request access to a user’s Octolane workspace with specific scopes:
ScopeAccess
crm:readSearch and read deals, contacts, companies, activity
crm:writeCreate and update deals, contacts, companies, notes
signal:readRead Signal website visitor data
pipeline:readQuery pipeline data and ask natural language questions
pipeline:writeUpdate deal stages and pipeline configuration
OAuth flow will follow the standard authorization code grant with PKCE.

​
Scopes and permissions

API key authentication gives full access to all MCP tools. The key inherits the permissions of the workspace it belongs to.
Tool categoryRequired permission
Search & queryRead access to CRM data
Create & updateWrite access to CRM data
get_signal_visitorsSignal enabled on your workspace
ask_pipelineRead access to CRM data
All team members with API access can generate keys. Workspace admins can revoke any key from Settings > Integrations > API.

​
Security best practices

Add your MCP config file to .gitignore. If you accidentally commit a key, revoke it immediately in Settings and generate a new one.
# Cursor MCP config
.cursor/mcp.json

# Claude Desktop config is in your home directory,
# so it's not in your repo by default
Some MCP clients support environment variable substitution. If yours does:
{
  "mcpServers": {
    "octolane": {
      "url": "https://mcp.octolane.com/mcp",
      "headers": {
        "X-API-Key": "${OCTOLANE_API_KEY}"
      }
    }
  }
}
Generate a new API key every 90 days as a best practice. Old keys can be revoked without downtime - generate the new key first, update your configs, then revoke the old one.
If you use Octolane MCP in multiple places (Claude, Cursor, a custom integration), consider generating separate keys for each so you can revoke access to one without affecting the others.
Check your API usage in Settings > Integrations > API to see request counts and spot any unexpected activity. Unusual spikes may indicate a compromised key.

​
Rate limits

The MCP server shares rate limits with the REST API:
LimitValue
Requests per minute100 per API key
Concurrent connections10 per API key
Max response size5 MB
When you hit a rate limit, the server returns a 429 status with a Retry-After header. Most MCP clients handle this automatically.

​
Troubleshooting

  • Verify your API key is correct - copy it fresh from Settings
  • Make sure you restarted your AI client after adding the config
  • Check that the config JSON is valid (no trailing commas, correct nesting)
  • Try the server URL directly in a browser to verify it’s reachable
  • Your API key may have been revoked - check Settings > Integrations > API
  • Make sure the header name is exactly X-API-Key (case-sensitive)
  • Verify there are no extra spaces or newlines in the key value
  • You’re hitting the rate limit (100 requests/minute)
  • Wait for the duration specified in the Retry-After header
  • If you consistently hit limits, contact us about higher rate limits for your workspace