# MCP Server

> Beta feature: this MCP Server is currently not open to the public.

Use the Signitic MCP Server to connect AI clients over HTTP and query read-only business data for a single Signitic workspace. The public MCP surface is intentionally bounded to support and operational use cases around users, campaigns, groups, workspace coverage, and business statistics.

Access is not open to the public yet. The documentation below describes the planned public MCP surface, but it is not available for customers at this time.

## Endpoint

<mark style="color:blue;">HTTP</mark> `https://mcp.signitic.com/mcp`

## Headers

| Name                                        | Type   | Description                                                   |
| ------------------------------------------- | ------ | ------------------------------------------------------------- |
| x-api-key<mark style="color:red;">\*</mark> | String | A Signitic API key belonging to a workspace with MCP enabled. |

## Transport

The current MCP exposure is HTTP-only. `stdio` is not supported on this server.

Use an MCP client that supports HTTP transport and custom headers, then send `x-api-key` with every request.

## Authentication and scope

* Every MCP session is resolved from the `x-api-key` header.
* The API key is mapped to exactly one workspace and MCP must be enabled on that workspace.
* All tools are read-only.
* Cross-workspace access is blocked. The optional `workspacePublicId` accepted by `stats_get_workspace_overview` must match the workspace resolved from the API key.

## Server guarantees

* Server name: `Signitic MCP`
* Version: `1.0.0`
* Default path: `/mcp`
* Session TTL: 1 hour
* Rate limit: 30 tool calls per minute, per tool, per workspace, per actor
* Audit logging: every successful and failed tool call is logged server-side

## Available tool domains

{% content-ref url="mcp-server/mcp-users" %}
[mcp-users](https://developers.signitic.app/reference/mcp-server/mcp-users)
{% endcontent-ref %}

{% content-ref url="mcp-server/mcp-campaigns" %}
[mcp-campaigns](https://developers.signitic.app/reference/mcp-server/mcp-campaigns)
{% endcontent-ref %}

{% content-ref url="mcp-server/mcp-groups" %}
[mcp-groups](https://developers.signitic.app/reference/mcp-server/mcp-groups)
{% endcontent-ref %}

{% content-ref url="mcp-server/mcp-workspace" %}
[mcp-workspace](https://developers.signitic.app/reference/mcp-server/mcp-workspace)
{% endcontent-ref %}

{% content-ref url="mcp-server/mcp-stats" %}
[mcp-stats](https://developers.signitic.app/reference/mcp-server/mcp-stats)
{% endcontent-ref %}

## Public tool catalog

| Domain      | Tools                                                                                                                       |
| ----------- | --------------------------------------------------------------------------------------------------------------------------- |
| `user`      | `user_list`, `user_count`, `user_find`, `user_get_summary`, `user_get_support_context`                                      |
| `campaign`  | `campaign_list`, `campaign_find`, `campaign_get_summary`, `campaign_get_support_context`                                    |
| `group`     | `group_list`, `group_find`, `group_get_summary`, `group_get_support_context`                                                |
| `workspace` | `workspace_get_user_profile_completeness`, `workspace_get_campaign_assignment_overview`, `workspace_get_group_completeness` |
| `stats`     | `stats_get_workspace_overview`, `stats_get_campaign_performance`, `stats_get_user_metrics`                                  |

## Authentication failure

If the API key is missing or invalid, the server returns a JSON-RPC error response such as:

```json
{
  "jsonrpc": "2.0",
  "id": "",
  "error": {
    "code": -32001,
    "message": "Invalid API key.",
    "data": {
      "reason": "invalid_api_key"
    }
  }
}
```

with HTTP status `401 Unauthorized`.

If the API key resolves a workspace where MCP is disabled, the same JSON-RPC envelope is returned with:

* `message = "MCP is disabled for this workspace."`
* `error.data.reason = "mcp_disabled"`

## Tool execution errors

Tool-level validation, access, not-found, and rate-limit failures are returned as MCP execution errors by the server.

Common cases:

* Invalid parameters: for example an invalid public ID format, an invalid date, or `from > to`
* Not found: the requested user or campaign does not belong to the current workspace
* Rate limited: too many MCP tool requests

## Identifier formats

| Identifier          | Format                            |
| ------------------- | --------------------------------- |
| `userPublicId`      | `usr_<26 lowercase base32 chars>` |
| `campaignPublicId`  | `cp_<26 lowercase base32 chars>`  |
| `groupPublicId`     | `grp_<26 lowercase base32 chars>` |
| `workspacePublicId` | `<26 lowercase base32 chars>`     |

## Notes for clients

* Search tools are bounded to a maximum of 10 results per request.
* `user_list`, `campaign_list`, and `group_list` are capped to the first 25 readable records.
* `stats_get_campaign_performance` and `stats_get_user_metrics` default to a 30-day window, and infer the missing bound when only `from` or `to` is provided.
* Stats periods are limited to 90 inclusive days when both `from` and `to` are provided.
* `stats_get_workspace_overview` requires both `from` and `to`.
* On the dedicated MCP host, only `/` and `/mcp` are exposed.