---
title: "MCP server"
canonical: "http://docs.symios.ai/integration/mcp"
lang: "en"
---

# MCP server

Symios exposes a hosted [Model Context Protocol](https://modelcontextprotocol.io/) server so partners can use Integration data directly inside LLM apps (ChatGPT, Claude.ai, Copilot, Gemini) and developer tools (Cursor, Claude Code, VS Code Copilot).

Use MCP when you want an assistant to call curated tools. Use the [REST Integration API](http://docs.symios.ai/integration.md) when you need raw HTTP from your own backend.

## Endpoint

```
https://mcp.symios.ai/mcp
```

Transport: Streamable HTTP. OAuth issuer: `https://mcp.symios.ai`.

## Prerequisites

1. Integration feature enabled for your company.
2. An API credential in the Symios dashboard (**API Credentials**). See [Authentication](http://docs.symios.ai/integration/authentication.md).
3. Integration rate limit still applies: **120 requests/minute** per credential. `get_overview` uses two Integration calls.

## Auth at a glance

| Client type | How to authenticate |
| --- | --- |
| LLM apps (ChatGPT, Claude.ai, Copilot, Gemini) | OAuth — paste the MCP URL, complete browser login/consent |
| Dev tools (Cursor, Claude Code, Claude Desktop, VS Code) | Remote URL + `X-Api-Key` and `X-Api-Secret` headers |

## Connect LLM apps

### ChatGPT

1. Open **Settings → Apps & Connectors** (or Developer mode connectors).
2. Add a custom MCP server / connector.
3. Server URL: `https://mcp.symios.ai/mcp`.
4. Complete the Symios OAuth consent: sign in to the dashboard, pick an API credential, enter its secret.
5. Verify: ask ChatGPT to list your Symios brands.

### Claude.ai

1. Open **Customize → Connectors**.
2. Add a custom connector with URL `https://mcp.symios.ai/mcp`.
3. Complete OAuth (callback is handled by Claude).
4. Verify with a prompt such as “List my Symios brands”.

### Microsoft Copilot

1. In Copilot Studio (or VS Code Copilot MCP settings), add an MCP server.
2. URL: `https://mcp.symios.ai/mcp`.
3. Prefer OAuth when the product offers it; otherwise configure API key headers as for Cursor.
4. Discover tools and run a simple `list_brands` call.

### Gemini

1. In your Gemini / Workspace MCP connector settings, add a remote MCP server.
2. URL: `https://mcp.symios.ai/mcp`.
3. Complete OAuth when prompted.
4. Verify by asking Gemini to list Symios brands.

## Connect dev tools

Create a credential in the dashboard and copy `api_key` + `api_secret` (secret is shown once).

### Cursor

Add to MCP config (`mcp.json`):

```json
{
  "mcpServers": {
    "symios": {
      "url": "https://mcp.symios.ai/mcp",
      "headers": {
        "X-Api-Key": "sk_live_…",
        "X-Api-Secret": "your_secret"
      }
    }
  }
}
```

### Claude Code / Claude Desktop

```json
{
  "mcpServers": {
    "symios": {
      "type": "http",
      "url": "https://mcp.symios.ai/mcp",
      "headers": {
        "X-Api-Key": "${SYMIOS_API_KEY}",
        "X-Api-Secret": "${SYMIOS_API_SECRET}"
      }
    }
  }
}
```

### VS Code Copilot

Configure a remote MCP server with the same URL and `X-Api-Key` / `X-Api-Secret` headers (or OAuth if your Copilot build supports it).

### Local development

When running docker-compose locally, use `http://localhost:50086/mcp` with the same headers.

## Available tools

| Tool | Purpose |
| --- | --- |
| `list_brands` | Company brands |
| `list_query_sets` | Query sets for a brand |
| `get_query_set` | Set details + engines |
| `list_runs` | Published runs |
| `get_overview` | Home summary + competitive context |
| `get_presence` | Presence metric (`metric` enum) |
| `get_life` | Life metric |
| `get_gravity` | Gravity metric |
| `get_scout` | Scout metric |
| `get_market` | Market metric |

Typical flow: `list_brands` → `list_query_sets` → `list_runs` → section tool(s).

## Errors and troubleshooting

- **401 / not authorized** — wrong key/secret, disabled credential, or OAuth cancelled. Recreate or rotate credentials; reconnect the app.
- **Rate limited** — wait and retry; reduce parallel tool calls. See [Errors](http://docs.symios.ai/integration/errors.md).
- **Query set not found** — wrong `query_set_id` for the company.
- **OAuth consent expired** — start the connector setup again from the LLM app.
- **Tool not found** — update the client / reconnect so it refreshes the tool list.

## Security

- Never paste API secrets into chat prompts.
- Rotate secrets in the dashboard if a key may be exposed.
- OAuth bindings store encrypted credentials server-side; LLM apps receive only opaque access tokens.