MCP

Shilo’s hosted Model Context Protocol (MCP) server gives compatible AI assistants and agent frameworks secure, structured access to your Shilo data. Connect once, then use natural language to find contacts and users, inspect calls, prepare for appointments, and retrieve performance metrics.

The Shilo MCP server is read-only. It does not create, update, or delete data in Shilo or your CRM.

Quickstart

1. Generate a Shilo API key

The MCP server uses the same API keys as the Shilo REST API. An owner or admin can create one in Settings → API Keys → Generate API Key. Keep Read-only Key turned on, give the key a descriptive name such as MCP - Claude or MCP - Cursor, and copy it immediately. Shilo will not display the secret again. See Authentication for full key-management and security guidance.

2. Add Shilo to your MCP client

Use the following connection details:

Setting	Value
Name	`Shilo`
Transport	Streamable HTTP
URL	`https://mcp.shilo.ai`
Authentication	`x-api-key: YOUR_SHILO_API_KEY`
Alternate authentication	`Authorization: Bearer YOUR_SHILO_API_KEY`

Your client must support remote Streamable HTTP servers and custom request headers. Many MCP clients accept configuration similar to this:

{
  "mcpServers": {
    "shilo": {
      "url": "https://mcp.shilo.ai",
      "headers": {
        "x-api-key": "YOUR_SHILO_API_KEY"
      }
    }
  }
}

Configuration fields vary by client. If your client supports environment-variable or secret references, use one instead of storing the key directly in the configuration file.

3. Confirm the connection

Save the configuration, restart or reconnect your MCP client if required, and ask it to list the available Shilo tools. You can separately verify that the hosted server is available:

curl https://mcp.shilo.ai/health

A healthy server returns OK. This health check confirms availability only; it does not validate your API key.

Available tools

All tools are read-only and return structured data that an MCP client can reason over or pass to another workflow.

Tool	What it does	Key inputs
`prepare_appointment_context`	Builds a compact appointment-prep packet with the user, contact, recent calls and analysis, and available Shilo Signals.	`external_user_id`, `external_contact_id`, optional `recent_calls_limit`
`search_contacts`	Finds contacts by name, email, phone, or external contact ID.	Search fields plus optional `limit`, `cursor`, and `sort`
`get_contact_context`	Retrieves a contact with optional Shilo Signal and recent-call context.	`external_contact_id`, optional `include_signal`, `include_recent_calls`, and `recent_calls_limit`
`search_users`	Finds Shilo users—agents and team members—by name, email, or external user ID.	Search fields plus optional `limit`, `cursor`, and `sort`
`get_user_context`	Retrieves a user with optional Shilo Signal and performance metrics.	`external_user_id`, optional `include_signal` and `include_metrics`
`list_calls`	Lists recent calls using cursor-based pagination.	Optional `limit`, `cursor`, and `sort`
`get_call_context`	Retrieves one call with optional analysis and transcript context.	`call_id`, optional `include_analysis` and `include_transcript`
`list_appointments`	Lists appointment recordings using cursor-based pagination.	Optional `limit`, `cursor`, and `sort`
`get_performance_metrics`	Retrieves dashboard-aligned metrics for the API key’s integration, a user, or a contact.	`target_type` and, when needed, `external_user_id` or `external_contact_id`

Identifiers and pagination

Context tools use the external IDs from your connected CRM. Use search_contacts or search_users first when you do not already know an ID. get_call_context uses the Shilo call ID returned by list_calls. Search and list tools return 25 records by default and accept a maximum limit of 100. When pagination.has_more is true, pass pagination.next_cursor into the next request. Appointment prep and contact context tools return up to three recent calls by default and accept a maximum of five. Optional data may not exist for every record. Context tools return a warnings array when a requested signal, analysis, transcript, or related object cannot be included.

Example prompts

Once connected, try prompts like:

“Find Jamie Client, then prepare me for my next appointment with them using recent calls and Shilo Signals.”
“Show me the context for the most recent call, including the analysis and transcript.”
“Find the user with the email alex@example.com and summarize their current performance metrics.”
“List the most recent appointments and identify which contacts need follow-up.”
“Find a contact by phone number and summarize what happened in their recent conversations.”

Your MCP client decides when and how to call tools. For more reliable results, name the contact or user clearly and specify whether you want signals, metrics, recent calls, analysis, or transcript data.

Security

Treat your Shilo API key like a password.

Use a dedicated read-only key for each MCP client or integration.
Never commit a key to source control or paste it into a public prompt.
Prefer environment variables or a secrets manager when your client supports them.
Revoke unused or exposed keys from Settings → API Keys.
Remember that each key is scoped to its associated Shilo integration.

Troubleshooting

The client returns `401 Unauthorized`

The key is missing, invalid, mistyped, or revoked. Confirm that the configured header is either x-api-key or Authorization: Bearer and that it contains the complete key.

The client cannot connect or discover tools

Confirm that the URL is exactly https://mcp.shilo.ai and that the client supports Streamable HTTP plus custom headers. Save the configuration and restart the client if it does not automatically reconnect.

A contact, user, or call is not found

Check that you are using the expected identifier and that the API key belongs to the Shilo integration that contains the record. Search for the contact or user first when you are unsure of the external ID.

Optional context is missing

Signals, analyses, transcripts, and metrics are not available for every record. Review the tool’s warnings array for the specific reason.

Get Started

Core Concepts

Guides

Quickstart

1. Generate a Shilo API key

2. Add Shilo to your MCP client

3. Confirm the connection

Available tools

Example prompts

Security

Troubleshooting

The client returns `401 Unauthorized`

The client cannot connect or discover tools

A contact, user, or call is not found

Optional context is missing

​Quickstart

​1. Generate a Shilo API key

​2. Add Shilo to your MCP client

​3. Confirm the connection

​Available tools

​Identifiers and pagination

​Example prompts

​Security

​Troubleshooting

​The client returns 401 Unauthorized

​The client cannot connect or discover tools

​A contact, user, or call is not found

​Optional context is missing

Quickstart

1. Generate a Shilo API key

2. Add Shilo to your MCP client

3. Confirm the connection

Available tools

Identifiers and pagination

Example prompts

Security

Troubleshooting

The client returns `401 Unauthorized`

The client cannot connect or discover tools

A contact, user, or call is not found

Optional context is missing