Skip to main content
The ShingleAI MCP server uses MCP keys to authenticate connections. MCP keys are separate from API keys and provide fine-grained control over which tools your AI agents can access.

​
Creating an MCP Key

  1. Sign in to the ShingleAI Dashboard
  2. Navigate to Settings > API Keys
  3. Click Create MCP Key
  4. Give your key a descriptive name (e.g., “Claude Desktop” or “Automation Agent”)
  5. Select the resource permissions your agent needs
  6. Click Create and copy your key immediately
Your MCP key is only shown once when created. Store it securely - you won’t be able to see it again. If you lose your key, you’ll need to create a new one.

​
Using Your MCP Key

Include your MCP key in the Authorization header when connecting to the MCP server: 
Authorization: Bearer your-mcp-key

curl https://mcp.shingleai.com/sse \
  -H "Authorization: Bearer mcp_live_abc123..."

​
Permission-Based Tool Filtering

MCP keys include granular permissions that control which tools are available to your agent. When you connect, the server only registers tools that match your key’s permissions.

​
Available Resource Permissions

ResourceActionsTools Affected
contactsread, write, deleteContact management tools
customersread, write, deleteCustomer and transaction tools
businessesread, write, deleteBusiness profile tools
messagesread, write, deleteMessage reading and search tools
automationsread, write, deleteAutomation workflow tools
domainsread, write, deleteDomain management tools
tasksread, write, deleteTask management tools
filesread, write, deleteFile and folder tools
resourcesreadResource listing tools

​
Permission Inheritance

Permissions follow a hierarchical model. Granting access to a parent resource also grants access to its child resources:
  • contacts includes contacts.emails, contacts.phones, contacts.addresses
  • customers includes customers.transactions
  • businesses includes businesses.offerings, businesses.presence
  • domains includes domains.contacts, domains.registrations
A key with only read permission for contacts will have access to contact listing and search tools, but not tools that create or modify contacts.

​
Monthly Call Limits

MCP calls are metered based on your subscription tier:
TierMCP Calls/Month
Free500
Starter5,000
Professional50,000
EnterpriseUnlimited
Limits reset on your billing cycle anniversary date. Paid tiers include a 10% grace period for overages before service is paused.

​
Rate Limits

To ensure service stability, MCP connections are rate-limited to 100 requests per minute per MCP key. When you exceed the rate limit, the server returns a JSON-RPC error: 
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32004,
        "message": "Rate limit exceeded",
        "data": {
            "retryAfter": 60
        }
    }
}
Implement exponential backoff or request queuing in your agent to handle rate limiting gracefully.

​
Authentication Errors

​
401 Unauthorized

Returned when authentication fails: 
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32001,
        "message": "Invalid or missing MCP key"
    }
}
Common causes:
  • Missing Authorization header
  • Invalid or revoked MCP key
  • Malformed Bearer token (missing “Bearer ” prefix)
  • Expired MCP key

​
403 Forbidden

Returned when your key lacks permission for a specific action: 
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32003,
        "message": "Insufficient permissions for this tool"
    }
}
Or when you’ve exhausted your monthly call limit: 
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32003,
        "message": "Monthly MCP call limit exceeded",
        "data": {
            "upgradeUrl": "https://www.shingleai.com/pricing"
        }
    }
}

​
Security Best Practices

Create a dedicated MCP key for each AI assistant or automation. This makes it easy to revoke access for a specific agent without affecting others.
Follow the principle of least privilege. If your agent only needs to read contacts, don’t grant write or delete permissions.
Never commit MCP keys to version control. Use environment variables or a secrets manager.
# .env (never commit this file)
SHINGLEAI_MCP_KEY=mcp_live_abc123...
Create new MCP keys and revoke old ones regularly. This limits exposure if a key is compromised.
Review your MCP key activity in the dashboard. Revoke any keys showing unexpected activity.

​
Next Steps

Connection Guide

Learn how to connect AI agents to the MCP server

Available Tools

Explore the full list of available tools