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

# MCP server

> Connect coding agents and chat clients to your reconciled CRM data over the Model Context Protocol.

Syntaxia exposes a read-only Model Context Protocol server so coding agents and chat clients can browse reconciled CRM accounts, contacts, reps, and opportunities from the org you authenticate as.

|               |                                                                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Endpoint**  | `https://app.syntaxia.com/mcp`                                                                                                             |
| **Transport** | HTTP (streamable, JSON-RPC)                                                                                                                |
| **Tools**     | [`read_profile`](#read-profile), [`list_accounts`](#list-accounts), [`search_accounts`](#search-accounts), [`read_account`](#read-account) |

## Authentication

Syntaxia supports two authentication paths:

* **OAuth 2.1** (recommended for Claude.ai web). The client registers itself, you approve consent in Syntaxia, and the access token is issued and stored automatically. Nothing to copy or paste.
* **Bearer token** (Claude Desktop, Claude Code, Cursor, VS Code). You generate a token under **Settings → Integrations** and put it in the client's config.

Both paths bind the resulting token to a user-and-org pair, so the token alone determines what data Claude sees. To connect Claude to a different organization, generate a new token (or re-authorize) for that workspace.

<Card title="Sign in to Syntaxia" icon="key" href="https://app.syntaxia.com/signin" horizontal>
  Generate a token at **Settings → Integrations**, or initiate an OAuth flow from the Claude.ai connector dialog.
</Card>

## Client setup

Tabs are organized from easiest to most-control. The endpoint is the same for all clients: `https://app.syntaxia.com/mcp`.

<Tabs>
  <Tab title="Claude.ai web">
    Claude.ai uses OAuth 2.1 with Dynamic Client Registration. You don't need to generate or paste a token.

    <Steps>
      <Step title="Open the connector dialog">
        In Claude.ai, go to **Settings → Connectors** and click **Add custom connector**.
      </Step>

      <Step title="Enter the endpoint">
        Name the connector (eg. `Syntaxia`) and paste the URL:

        ```
        https://app.syntaxia.com/mcp
        ```

        Leave **OAuth Client ID** and **OAuth Client Secret** empty under Advanced settings. Claude will register itself automatically.
      </Step>

      <Step title="Approve consent">
        Click **Add**. Claude opens a Syntaxia sign-in popup. After you sign in, the consent screen asks which organization to authorize. Pick one and click **Allow**.
      </Step>

      <Step title="Connected">
        The connector status flips to **Connected** and the four MCP tools (`read_profile`, `list_accounts`, `search_accounts`, `read_account`) become available to Claude.
      </Step>
    </Steps>

    To switch organizations, click **Revoke** on the connector card in Claude.ai, then re-add it and pick the other organization on the consent screen.
  </Tab>

  <Tab title="Claude Desktop">
    Generate a token at **Settings → Integrations** in Syntaxia first. Then edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) and add a Syntaxia entry under `mcpServers`. Replace `<your_token>` with the token you just generated.

    ```json theme={null}
    {
      "mcpServers": {
        "syntaxia": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://app.syntaxia.com/mcp",
            "--header",
            "Authorization: Bearer <your_token>"
          ]
        }
      }
    }
    ```

    Restart Claude Desktop after editing.
  </Tab>

  <Tab title="Claude Code">
    Generate a token at **Settings → Integrations** in Syntaxia, then register Syntaxia with the Claude Code CLI. Run this once per machine, substituting `<your_token>`.

    ```bash theme={null}
    claude mcp add syntaxia --transport http https://app.syntaxia.com/mcp --header "Authorization: Bearer <your_token>"
    ```
  </Tab>

  <Tab title="Cursor">
    Generate a token at **Settings → Integrations** in Syntaxia first. Then add a `.cursor/mcp.json` file at your project root (or in `~/.cursor/mcp.json` for global use), substituting `<your_token>`.

    ```json theme={null}
    {
      "mcpServers": {
        "syntaxia": {
          "url": "https://app.syntaxia.com/mcp",
          "headers": {
            "Authorization": "Bearer <your_token>"
          }
        }
      }
    }
    ```

    Reload Cursor after saving.
  </Tab>

  <Tab title="VS Code">
    Generate a token at **Settings → Integrations** in Syntaxia first. Then add a `.vscode/mcp.json` file at your workspace root. VS Code prompts for the token on first connection.

    ```json theme={null}
    {
      "servers": {
        "syntaxia": {
          "type": "http",
          "url": "https://app.syntaxia.com/mcp",
          "headers": {
            "Authorization": "Bearer ${input:syntaxia_token}"
          }
        }
      },
      "inputs": [
        {
          "id": "syntaxia_token",
          "type": "promptString",
          "description": "Syntaxia MCP token",
          "password": true
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## Tools

Always call `search_accounts` before `read_account` unless you already have a `unified_account_id` in context.

### read\_profile

Returns the authenticated user's identity, organization, and role.

No arguments.

```json Example response theme={null}
{
  "identity_email": "user@acme.com",
  "name": "Jane Doe",
  "organization": { "slug": "0000001", "name": "Acme" },
  "role": "owner"
}
```

### list\_accounts

Lists active unified accounts in the authenticated organization, paginated.

<ParamField body="limit" type="integer" default="20">
  Page size (max 100).
</ParamField>

<ParamField body="offset" type="integer" default="0">
  Row offset for pagination.
</ParamField>

<ParamField body="source_system_id" type="uuid">
  Optional. Restrict to clusters with a member contributed by this source.
</ParamField>

```json Example response theme={null}
{
  "accounts": [
    {
      "unified_account_id": "8f3c...",
      "canonical_name": "Acme Corp",
      "canonical_domain": "acme.com",
      "member_count": 2,
      "contact_count": 14,
      "opportunity_total_amount": "120000.00",
      "updated_at": "2026-05-13T10:21:00Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 187 }
}
```

### search\_accounts

Fuzzy-searches unified accounts by name (pg\_trgm similarity).

<ParamField body="query" type="string" required>
  Search query (1 to 100 characters).
</ParamField>

<ParamField body="limit" type="integer" default="10">
  Page size (max 50).
</ParamField>

```json Example response theme={null}
{
  "matches": [
    {
      "unified_account_id": "8f3c...",
      "canonical_name": "Acme Corp",
      "canonical_domain": "acme.com",
      "similarity": 0.9123
    }
  ],
  "query": "acme"
}
```

### read\_account

Returns the full reconciled payload for one unified account.

<ParamField body="unified_account_id" type="uuid" required>
  Unified account UUID, typically obtained from `search_accounts` or `list_accounts`.
</ParamField>

```json Example response theme={null}
{
  "account": { "id": "8f3c...", "name": "Acme Corp", "domain": "acme.com", "...": "..." },
  "contacts": [ { "...": "..." } ],
  "reps": [ { "...": "..." } ],
  "opportunities": [ { "...": "..." } ],
  "relationships": { "...": "..." }
}
```