---
updatedAt: 2026-11-06T15:26:37.000Z
agentTools:
  projectIndex: https://developer.unipile.com/v2.0/llms.txt
---

# Model context protocol (MCP)

Connect your AI tools to Unipile using MCP

The Model Context Protocol (MCP) is a standard for connecting Large Language Models (LLMs) to platforms like Unipile. Once connected, your AI assistants can interact with your Unipile accounts on your behalf.

<br />

# Dashboard setup guide

On **Overview**, click **Connect my project**, then select **MCP** and your client.

* Leave **Access connected accounts** off to use the API documentation without an API key. The guide provides a configuration without authentication headers.
* Enable **Access connected accounts** to allow account actions. Use **Manage scopes** to create a dedicated Scope and assign the accounts, then create an Account API Key for that Scope. Replace `YOUR_SCOPED_ACCOUNT_API_KEY` in the generated configuration with your key locally.

Copy the command or configuration into your client, restart it or reopen the session, and start a new conversation. The guide also offers an example prompt and a control to copy setup instructions for your coding assistant.

# Installation

## 1. Choose documentation only or account actions

The MCP can be used simply to help your agent understand the Unipile API design and explore available endpoints.

For documentation only, omit the `X-API-KEY` header from the configurations below. You can also configure a scoped Account API Key to allow the agent to call account [Methods](https://developer.unipile.com/v2.0/docs/methods) on your behalf.

Before enabling account actions, create a dedicated [Scope](https://developer.unipile.com/v2.0/docs/scopes), assign only the accounts the client should access, and create a [scoped Account API Key](https://developer.unipile.com/v2.0/docs/api-keys#scoped-account-api-keys) for that Scope.

Use this scoped key in the examples below. It limits the client to the accounts assigned to its Scope.

Do not use a Service Key or a global Account API Key with an MCP client. Both provide access to every account in the Application. Keep your scoped key secret and only configure it in clients and environments you trust.

<br />

## 2. Set up your client

Choose your MCP client, then follow the instructions.

<Tabs>
  <Tab title="Cursor">
    **Add to `~/.cursor/mcp.json`:**

    ```json
    {
      "mcpServers": {
        "unipile": {
          "url": "https://developer.unipile.com/mcp?branch=v2.0",
          "headers": {
            "X-API-KEY": "your-scoped-api-key"
          }
        }
      }
    }
    ```

  </Tab>

  <Tab title="Windsurf">
    **Add to `~/.codeium/windsurf/mcp_config.json`:**

    ```json
    {
      "mcpServers": {
        "unipile": {
          "url": "https://developer.unipile.com/mcp?branch=v2.0",
          "headers": {
            "X-API-KEY": "your-scoped-api-key"
          }
        }
      }
    }
    ```

  </Tab>

  <Tab title="Claude Code">
    **Run:**

    ```bash
    claude mcp add --transport http \
      --scope user \
      --header "X-API-KEY: your-scoped-api-key" \
      unipile "https://developer.unipile.com/mcp?branch=v2.0"
    ```

    Run `claude mcp list` to verify the connection. You can also use `/mcp` from a Claude Code session.

  </Tab>

  <Tab title="Claude Desktop">
    **Add to `claude_desktop_config.json`:**

    ```json
    {
      "mcpServers": {
        "unipile": {
          "type": "http",
          "url": "https://developer.unipile.com/mcp?branch=v2.0",
          "headers": {
            "X-API-KEY": "your-scoped-api-key"
          }
        }
      }
    }
    ```

    Restart Claude Desktop after saving the file.

  </Tab>

  <Tab title="Codex / ChatGPT desktop">
    Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share the same MCP configuration.

    **Add to `~/.codex/config.toml`:**

    ```toml
    [mcp_servers.unipile]
    url = "https://developer.unipile.com/mcp?branch=v2.0"
    http_headers = { X-API-KEY = "your-scoped-api-key" }
    ```

    Restart the client after saving the file. In Codex CLI, run `codex mcp list` to verify the connection. In the ChatGPT desktop app, open **Settings > MCP servers** or enter `/mcp` in the composer.

  </Tab>
</Tabs>

<br />

## Next step

Once configured, you can test your MCP server connection:

1. **Open your AI client** (Cursor, Windsurf, Claude, Codex, or ChatGPT desktop)
2. **Start a new chat** with the AI assistant
3. **Ask about Unipile or request an account action**. For example:
   * "How do I \[common use case]?"
   * "Show me an example of \[API functionality]"
   * "Create an \[integration type] using Unipile"
   * "Send a message to \[xxxx] using account acc\_1234521321"
   * "List all emails in the <example@gmail.com> inbox"

The AI can consult the Unipile API Reference. When configured with a scoped key, it can also access the account data allowed by that Scope through the MCP server.

<br />

# Available tools

* `list-specs` - Lists all API specs available in the project, with their titles
* `list-endpoints` - Returns all API paths and HTTP methods with their summaries
* `get-endpoint` - Returns full detail on a specific endpoint: description, parameters, security
* `get-request-body` - Returns the request body schema for an endpoint
* `get-response-schema` - Returns the response schema for a specific endpoint and status code
* `list-security-schemes` - Lists all authentication methods defined in your API spec
* `search-specs` - Case-insensitive search across all paths, operations, and schemas
* `execute-request` - Makes a live API call and returns the response. Requires auth headers to be forwarded
* `get-code-snippet` - Generates a working code snippet for any endpoint in any programming language