> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shilo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect AI assistants and agent frameworks to Shilo's hosted MCP server and explore the available read-only tools.

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](/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:

```json theme={null}
{
  "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:

```bash theme={null}
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](mailto: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.