Skip to main content
MCP keys allow AI agents and assistants to access your ShingleAI organization through the Model Context Protocol (MCP). This guide covers creating, configuring, and securing your MCP keys.
MCP keys are separate from API keys. Use MCP keys for AI agent integrations (Claude, Cursor, etc.) and API keys for REST API access.

​
Prerequisites

  • You must be an Owner to manage MCP keys
  • Admins and Users cannot create, view, or revoke MCP keys

​
Creating an MCP Key

To create a new MCP key:
  1. Navigate to Settings > Security > MCP Keys
  2. Click Create MCP Key
  3. Enter a descriptive name (e.g., “Claude Desktop” or “Automation Agent”)
  4. Configure resource permissions (see below)
  5. Click Create
The full MCP key is displayed only once after creation. Copy it immediately and store it securely. You cannot retrieve the full key later.

​
MCP Key Format

ShingleAI MCP keys follow this format: 
mcp_live_abc123...
  • mcp_ - Indicates an MCP key
  • live_ - Environment (live for production)
  • Followed by a unique identifier

​
Setting Permissions

MCP keys support fine-grained permissions that control which tools are available to your AI agent.

​
Permission Structure

Each permission specifies:
ComponentDescriptionExample
ResourceWhat the key can accesscontacts, messages
ActionWhat operations are allowedread, write, delete
When an AI agent connects with your MCP key, the server only registers tools that match the 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

​
Permission Inheritance

Permissions cascade to child resources. Granting access to a parent resource automatically includes its children:
  • contacts includes contacts.emails, contacts.phones, contacts.addresses
  • customers includes customers.transactions
  • businesses includes businesses.offerings, businesses.presence
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.

​
Usage Limits

​
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

MCP connections are rate-limited to 100 requests per minute per MCP key. Exceeding this limit returns an error with a retryAfter value.

​
Monitoring Key Usage

Track MCP key activity from the MCP Keys dashboard:
MetricDescription
Last UsedTimestamp of the most recent connection
CreatedWhen the key was created
StatusActive or Revoked
Monthly UsageCalls used this billing period

​
Revoking Keys

To revoke an MCP key:
  1. Navigate to Settings > Security > MCP Keys
  2. Find the key to revoke
  3. Click Revoke
  4. Confirm the action
Revoked keys cannot be restored. Any AI agent using the revoked key will immediately lose access.

​
When to Revoke

Revoke MCP keys immediately when:
  • A key may have been compromised
  • An employee with key access leaves the organization
  • An AI integration is decommissioned
  • A key shows unexpected activity

​
Security Best Practices

​
Key Storage

  • Never commit MCP keys to version control
  • Use environment variables or secret management services
  • Restrict file permissions on configuration files containing keys
export SHINGLEAI_MCP_KEY="mcp_live_abc123..."

​
Key Per Agent

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
  • Track usage per integration
  • Apply different permission scopes to different agents

​
Principle of Least Privilege

Grant only the permissions each agent needs:
  • Read-only keys for agents that only retrieve information
  • Resource-specific keys for focused integrations
  • Avoid granting delete permissions unless necessary

​
Audit Regularly

Review your MCP keys monthly:
  • Remove unused keys (no activity in 90+ days)
  • Verify permissions match current requirements
  • Check for unexpected usage patterns

​
Troubleshooting

​
Common Errors

ErrorCauseSolution
Invalid or missing MCP keyKey is incorrect, revoked, or missingVerify key value and status
Insufficient permissionsKey lacks required resource/actionUpdate key permissions or create new key
Rate limit exceededToo many requests per minuteImplement backoff in your agent
Monthly limit exceededExhausted monthly call quotaWait for reset or upgrade plan

​
Next Steps

MCP Server Guide

Learn about the MCP server and available tools

AI Integrations

Set up Claude, Cursor, and other AI assistants