# Cention MCP server

> Connect an MCP-capable AI agent to the Cention MCP server and it can work in one Cention workspace headless — read and update cases, contacts, the knowledge base, reports and more — through the same Partner API a developer integration uses. No UI, no screen scraping, no separate product: every tool is a Partner API operation.

Human-readable version: https://cention.com/developers/mcp

## Endpoint

Streamable HTTP, stateless, JSON responses. OAuth 2.0 bearer token required.

```
POST https://api.cention.com/partner-api/v1/mcp
```

| | |
|---|---|
| Transport | MCP Streamable HTTP, stateless. Each POST carries one JSON-RPC message or a batch of up to 50, and is answered with `application/json`. No session id, no SSE stream; `GET` and `DELETE` return `405`. |
| Protocol versions | `2025-11-25`, `2025-06-18`, `2025-03-26`. A client asking for another version is offered `2025-11-25`. A request without an `MCP-Protocol-Version` header is treated as `2025-03-26`; an unsupported one gets `400`. |
| Methods | `initialize`, `ping`, `tools/list`, `tools/call`. Notifications get `202` with no body. |
| Capabilities | `tools` only (`listChanged: false`). No resources, prompts or sampling. |
| Server info | name `cention-api-gateway`, title `Cention API gateway`, version `1.0.0`. |

## Access

Two things must be in place before an agent can connect:

1. **MCP access is switched on for the workspace.** It is off by default, and Cention switches it on per customer. Contact us (https://cention.com/contact) or your account manager to have it enabled. Without it every request gets `403 MCP_NOT_ENABLED`. Switching it off takes effect within 30 seconds.
2. **The agent has a Partner API token.** Cention creates an OAuth client for the workspace with the scopes the agent may use. Exchange its credentials for a token:

```bash
BASE_URL="https://api.cention.com/partner-api"

TOKEN=$(curl -s -X POST "$BASE_URL/v1/oauth/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=cases:read contacts:read knowledge:read" | jq -r .access_token)
```

Send it on every MCP request as `Authorization: Bearer <token>`. Tokens expire after one hour; when a request returns `401`, fetch a new one. The `scope` parameter is optional: leave it out to get all of the client's scopes, or narrow it to give an agent less than the client may do.

**The token's scopes decide which tools the agent sees.** `tools/list` only lists the tools the scopes allow, and calling any other tool is refused.

## Tools

Tools are typed: `tools/list` returns a JSON Schema for every tool's arguments (types, enums, limits, required fields), arguments are validated before the call is made, and unknown arguments are refused. A tool's arguments are one flat object — the operation's path parameters, query parameters and JSON body fields.

Every tool carries MCP annotations: `readOnlyHint` (the call changes nothing) and `destructiveHint` (the call closes or deletes something). Clients that ask the user before a write can rely on them.

The current set, by area. `?` marks an optional argument. `tools/list` is always the authoritative list.

### Cases

`list_cases(status?, channel?, area_id?, agent_id?, contact_id?, priority?, query?, cursor?, limit?, offset?, sort_by?, sort_dir?)` · `cases:read` · read-only

List the workspace's cases (conversations), newest first unless sorted otherwise.

`get_case_stats()` · `cases:read` · read-only

Case counts for the workspace (by state, channel and so on).

`get_case(case_id)` · `cases:read` · read-only

Get one case.

`get_case_history(case_id, limit?, offset?)` · `cases:read` · read-only

The case's event history (state changes, assignments, forwards).

`list_case_messages(case_id, limit?, offset?)` · `cases:read` · read-only

The messages in a case.

`create_case(org_id, area_id, channel, contact_id?, subject?, body?, body_html?, from_address?, from_name?, to_address?, cc_addresses?, priority?, language?, tags?, metadata?)` · `cases:write`

Open a new case, optionally with its first message.

`update_case(case_id, subject?, priority?, channel?, state_label?, due_date?, metadata?)` · `cases:write`

Change a case's subject, priority, channel, state label, due date or metadata.

`acquire_case(case_id)` · `cases:write`

Take ownership of a case.

`return_case(case_id, reason?)` · `cases:write`

Give a case back to its queue.

`forward_case(case_id, forward_type, target_id?, target_address?, include_history?, reason?)` · `cases:write`

Forward a case to another area, agent, team leader, external address or workflow.

`close_case(case_id, note?)` · `cases:write` · destructive

Close a case.

`reopen_case(case_id)` · `cases:write`

Reopen a closed case.

`create_case_message(case_id, direction, actor_type?, actor_id?, channel?, content_type?, body?, body_html?, subject?, from_address?, to_addresses?, cc_addresses?, bcc_addresses?, in_reply_to?, channel_metadata?, attachment_ids?)` · `cases:write`

Add a message to a case: `outbound` sends a reply to the customer, `internal` adds a note, `inbound` records a customer message.

`bulk_close_cases(case_ids, note?)` · `cases:write` · destructive

Close several cases at once.

`bulk_tag_cases(case_ids, tag_ids?, tag_names?)` · `cases:write`

Add tags (by id or by name) to several cases at once.

`bulk_forward_cases(case_ids, forward_type, target_id?, target_address?, include_history?)` · `cases:write`

Forward several cases at once.

### Contacts

`list_contacts(limit?, offset?)` · `contacts:read` · read-only

List the workspace's contacts (customers).

`search_contacts(channel?, identifier?, external_id?, name?, email?, phone?, q?, limit?)` · `contacts:read` · read-only

Find contacts by channel identity, external id, name, email, phone or free text.

`get_contact(contact_id)` · `contacts:read` · read-only

Get one contact with their channel identities.

`get_contact_history(contact_id)` · `contacts:read` · read-only

The contact's past cases.

`list_contact_notes(contact_id)` · `contacts:read` · read-only

Notes kept on a contact.

`create_contact(name?, company?, city?, postcode?, external_id?, metadata?, channels?)` · `contacts:write`

Create a contact, optionally with channel identities.

`update_contact(contact_id, name?, company?, city?, postcode?, external_id?, metadata?)` · `contacts:write`

Change a contact's details.

`remove_contact_channel(contact_id, channel_id)` · `contacts:write` · destructive

Remove a channel identity from a contact.

### Agents

`list_agents(status?, role?, group_id?, is_active?, cursor?, limit?)` · `agents:read` · read-only

List the workspace's agents.

`get_agent(agent_id)` · `agents:read` · read-only

Get one agent's profile.

`get_agent_stats(agent_id)` · `agents:read` · read-only

One agent's workload and performance figures.

`get_agent_skills(agent_id)` · `agents:read` · read-only

The skills assigned to an agent.

`get_presence_board()` · `agents:read` · read-only

Who is online, busy or away right now.

`get_agent_presence(agent_id)` · `agents:read` · read-only

One agent's current presence.

### Knowledge base

`list_knowledge_articles(limit?, offset?)` · `knowledge:read` · read-only

List the knowledge base articles.

`get_knowledge_article(article_id)` · `knowledge:read` · read-only

Get one knowledge base article.

`search_knowledge(query, area_id?, language?, top_k?)` · `knowledge:read` · read-only

Semantic search over the knowledge base.

`answer_from_knowledge(query, area_id?, language?, top_k?, include_sources?, case_id?)` · `knowledge:read` · read-only

Get an answer to a question, written from the knowledge base articles.

### Routing

`list_routing_rules(limit?, offset?)` · `routing:read` · read-only

List the rules that route incoming messages to areas.

`get_routing_rule(rule_id)` · `routing:read` · read-only

Get one routing rule.

`list_routing_groups(limit?, offset?)` · `routing:read` · read-only

List the routing groups (sets of areas).

`get_routing_group(group_id)` · `routing:read` · read-only

Get one routing group.

### Reports

`list_report_types()` · `reports:read` · read-only

The available report types with their dimensions and measures.

`query_report(date_from, date_to, report_type?, dimensions?, measures?, filters?, group_by?, order_by?, granularity?, limit?, offset?, timezone?)` · `reports:read` · read-only

Run a report over a period and return its rows.

`ask_report_question(question, context?)` · `reports:read` · read-only

Answer a question about the workspace's data in plain language, e.g. "How many email cases were closed last week?".

`list_scheduled_exports()` · `reports:read` · read-only

Reports that are emailed on a schedule.

`get_scheduled_export(export_id)` · `reports:read` · read-only

Get one scheduled export.

`create_report_export(report_config, format)` · `reports:export`

Start a file export of a report. Poll `get_report_export` until it is done.

`get_report_export(job_id)` · `reports:export` · read-only

Status of a report export.

`get_report_export_download(job_id)` · `reports:export` · read-only

A download link for a finished report export (returned as `download_url`).

`create_scheduled_export(name, report_type, schedule, recipients, format)` · `reports:export`

Email a report on a schedule.

`update_scheduled_export(export_id, name?, report_type?, schedule?, recipients?, format?, enabled?)` · `reports:export`

Change a scheduled export, or switch it on or off.

`delete_scheduled_export(export_id)` · `reports:export` · destructive

Delete a scheduled export.

### Notifications

`list_notification_templates()` · `notifications:read` · read-only

The workspace's notification templates.

`get_notification_template(template_id)` · `notifications:read` · read-only

Get one notification template.

### Usage

`get_current_usage()` · `metering:read` · read-only

Usage in the current billing period.

`get_usage_history(date_from, date_to, action?, channel?, granularity?)` · `metering:read` · read-only

Usage over a period, bucketed by time.

`get_usage_breakdown(date_from, date_to)` · `metering:read` · read-only

Usage over a period, broken down by action and channel.

`get_ai_vs_human_usage(date_from, date_to)` · `metering:read` · read-only

How much work AI handled compared with agents, over a period.

`get_usage_summary(date_from, date_to)` · `metering:read` · read-only

Usage totals over a period.

### AI assist

`suggest_reply(case_id, tone?, language?, area_instructions?, include_contact_history?, include_knowledge?, max_messages?, knowledge_top_k?)` · `ai:invoke`

Draft a reply to a case with the workspace's AI assistant. Nothing is sent.

### Webhooks

`list_webhooks(limit?, offset?)` · `webhooks:manage` · read-only

Webhook endpoints registered for this workspace.

`get_webhook(webhook_id)` · `webhooks:manage` · read-only

Get one webhook endpoint.

`list_webhook_deliveries(webhook_id, limit?, offset?)` · `webhooks:manage` · read-only

Recent delivery attempts to a webhook endpoint.

`create_webhook(url, events, description?)` · `webhooks:manage`

Register an HTTPS endpoint that receives events. The response includes the signing `secret`, shown only this once.

`update_webhook(webhook_id, url?, events?, description?, is_active?)` · `webhooks:manage`

Change a webhook endpoint, or switch it on or off.

`send_test_webhook(webhook_id)` · `webhooks:manage`

Send a synthetic test event to the webhook endpoint.

`delete_webhook(webhook_id)` · `webhooks:manage` · destructive

Remove a webhook endpoint.

### Argument conventions

- Ids (`case_id`, `contact_id`, …) may contain only letters, digits, `_` and `-`.
- Dates and times are ISO 8601 strings, e.g. `2026-11-01T00:00:00Z`.
- List arguments are JSON arrays, e.g. `"status": ["new", "queued"]`.
- List tools return pages: pass `limit` and `offset` (or the `cursor` from the previous page) to read further.

### Tool results

Every result is JSON with the HTTP status of the underlying Partner API call and its body:

```json
{"status": 200, "body": {"id": "case_123", "status": "queued", "...": "..."}}
```

It is returned as text content, and also as `structuredContent` from protocol `2025-06-18` on. `isError` is `true` when the status is `400` or higher, or when the arguments don't fit the tool — the message then says what is wrong (`Missing required argument(s): case_id.`, `Argument 'limit' must be at most 200.`). `get_report_export_download` adds `download_url`.

## Resources

None. The server exposes tools only.

The tools are built from the Partner API's OpenAPI document, which is public and can be read directly when an agent needs the full schemas:

```
GET https://api.cention.com/partner-api/openapi.json
```

## Configure your agent

Every client needs the endpoint URL and the header `Authorization: Bearer <token>`. Because tokens expire after an hour, a client configured with a fixed header must be given a fresh token when it starts getting `401`.

### Claude Code

```bash
claude mcp add --transport http cention https://api.cention.com/partner-api/v1/mcp \
  --header "Authorization: Bearer $TOKEN"
```

### Cursor

Add the server to `.cursor/mcp.json` (one project) or `~/.cursor/mcp.json` (all projects), and set `CENTION_MCP_TOKEN` in the environment Cursor starts from:

```json
{
  "mcpServers": {
    "cention": {
      "url": "https://api.cention.com/partner-api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CENTION_MCP_TOKEN}"
      }
    }
  }
}
```

### Claude Desktop

Claude Desktop's config file starts local (stdio) servers, so connect through the `mcp-remote` bridge, which forwards to the remote URL with the header. Open Settings → Developer → Edit Config and add:

```json
{
  "mcpServers": {
    "cention": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.cention.com/partner-api/v1/mcp",
        "--header",
        "Authorization:${CENTION_AUTH}"
      ],
      "env": {
        "CENTION_AUTH": "Bearer <token>"
      }
    }
  }
}
```

Claude Desktop's "Add custom connector" dialog cannot be used: it signs in with the interactive OAuth flow, and this server issues tokens with `client_credentials` only.

### Your own agent (Python)

With the official MCP Python SDK (`pip install mcp`):

```python
import asyncio

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

URL = "https://api.cention.com/partner-api/v1/mcp"


async def main(token: str) -> None:
    headers = {"Authorization": f"Bearer {token}"}
    async with streamablehttp_client(URL, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([tool.name for tool in tools.tools])
            result = await session.call_tool("list_cases", {"status": ["new"], "limit": 10})
            print(result.structuredContent)


asyncio.run(main("<token>"))
```

### Other MCP-capable agents

Point the client at the endpoint, select the Streamable HTTP transport and add the `Authorization` header. Clients that only speak stdio can use `mcp-remote` as shown for Claude Desktop.

### Raw JSON-RPC (cURL)

```bash
curl -s -X POST "$BASE_URL/v1/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

curl -s -X POST "$BASE_URL/v1/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

curl -s -X POST "$BASE_URL/v1/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_cases","arguments":{"status":["new","queued"],"limit":10}}}'
```

## Discovery

A request without a valid token gets `401` with an OAuth challenge pointing at the protected-resource metadata, so MCP clients can find out how to authenticate:

```
WWW-Authenticate: Bearer resource_metadata="https://api.cention.com/partner-api/.well-known/oauth-protected-resource"
```

| Document | Content |
|---|---|
| `GET /.well-known/oauth-protected-resource` (also `…/oauth-protected-resource/v1/mcp`) | RFC 9728: the MCP resource URL, its authorization server and the supported scopes |
| `GET /.well-known/oauth-authorization-server` | RFC 8414: token, revoke and introspect endpoints; grant type `client_credentials`; client authentication `client_secret_basic` / `client_secret_post` |

Both paths are under `https://api.cention.com/partner-api`.

## Errors

| Response | Meaning |
|---|---|
| HTTP `401` | Missing, invalid, revoked or expired token, or the OAuth client is deactivated. Fetch a new token. |
| HTTP `403` `MCP_NOT_ENABLED` | MCP access is not switched on for this workspace. |
| HTTP `403` `ORIGIN_NOT_ALLOWED` | A browser `Origin` that is not allowed. |
| HTTP `400` | Unsupported `MCP-Protocol-Version`, a body that is not JSON (`-32700`), or an empty or too large batch. |
| HTTP `405` | `GET` or `DELETE` on the endpoint; use `POST`. |
| HTTP `429` | Rate limit reached; wait for `Retry-After`. |
| HTTP `503` `MCP_ACCESS_UNAVAILABLE` | The workspace's MCP access could not be checked; retry after `Retry-After` (5 s). Access is never assumed. |
| JSON-RPC `-32600` | Not a valid JSON-RPC 2.0 request. |
| JSON-RPC `-32601` | Unknown method. |
| JSON-RPC `-32602` | Unknown tool, or a tool the token's scopes don't allow (the message names the missing scope). |
| JSON-RPC `-32603` | Internal error. |
| Tool result with `isError: true` | The arguments don't fit the tool, or the API call failed; `status` and `body` say why. |

## Rate limits

The MCP server shares the Partner API limits of the OAuth client (default 600 requests per minute and 50,000 per day). A tool call counts once, in the API operation that serves it. Any other MCP request (`initialize`, `tools/list`, `ping`, notifications) counts once per HTTP request.

## Safety

Unlike a documentation MCP server, this server acts on live customer data, and tools can write. What keeps that safe:

- **No extra power.** A tool call is served by the same Partner API operation a REST call would use, with the caller's own token: the same scope check, tenant pinning and rate limit. The agent can never do more than its token allows, and only in its own workspace.
- **Least privilege by scope.** Give an agent only the scopes it needs. A token with only `:read` scopes gets only read-only tools; `cases:write`, `contacts:write`, `reports:export`, `webhooks:manage` and `ai:invoke` add tools that change data or start work.
- **Destructive calls are marked.** Closes and deletes carry `destructiveHint: true`, so clients can ask a person before running them.
- **Internal calls are narrowly signed.** Each call to an internal service carries a short-lived token holding only the permissions that the operation needs, never admin rights.
- **Cention controls access.** MCP access is off until Cention switches it on for the workspace, and switching it off stops all agents within 30 seconds. Deactivating the OAuth client or revoking the token stops one agent at once.
- **Browsers are kept out.** Requests with a foreign `Origin` are refused (DNS-rebinding protection).
- **Calls are logged.** Every tool call is logged with the tool name, OAuth client, workspace and HTTP status.

Tool results contain the workspace's customer data (names, addresses, messages). That data is sent to whatever AI model the agent uses, so only connect models you are allowed to share it with. See https://cention.com/trust/security and https://cention.com/trust/dpa.

## How the tools stay in sync

The Partner API is the master record. The MCP server holds no list of tools of its own: it reads the Partner API's OpenAPI document and makes a tool of every operation that requires the partner OAuth token. When a Partner API operation is added, changed or removed, the MCP tool follows.

| Tool field | Comes from the API operation |
|---|---|
| Scopes | The operation's `OAuth2ClientCredentials` security requirement |
| Name | A pinned tool name, so names stay stable |
| Title and description | The operation's summary and description |
| Arguments | The operation's path parameters, query parameters and JSON body |
| `readOnlyHint` / `destructiveHint` | Set per operation; by default GET is read-only and DELETE destructive |

Tool names are part of the public contract. `tools/list` is always the authoritative list for your token.

## More

- Developers home: https://cention.com/developers
- Security Policy: https://cention.com/trust/security
- Contact (MCP access, OAuth clients): https://cention.com/contact
