Skip to content

DEVELOPERS / MCP SERVER

MCP server

Connect an MCP-capable AI agent 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.

Overview

No UI, no screen scraping, no separate product: every tool is a Partner API operation.

The agent works in one workspace, with the permissions of its OAuth token. The token's scopes decide which tools it sees, and tools that close or delete something are marked so your client can ask a person first.

Endpoint

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

POST https://api.cention.com/partner-api/v1/mcp
TransportMCP 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 versions2025-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.
Methodsinitialize, ping, tools/list, tools/call. Notifications get 202 with no body.
Capabilitiestools only (listChanged: false). No resources, prompts or sampling.
Server infoname 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 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:
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

ToolScopeWhat it does
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
write
Open a new case, optionally with its first message.
update_case(case_id, subject?, priority?, channel?, state_label?, due_date?, metadata?)cases:write
write
Change a case's subject, priority, channel, state label, due date or metadata.
acquire_case(case_id)cases:write
write
Take ownership of a case.
return_case(case_id, reason?)cases:write
write
Give a case back to its queue.
forward_case(case_id, forward_type, target_id?, target_address?, include_history?, reason?)cases:write
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
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
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
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
write
Forward several cases at once.

Contacts

ToolScopeWhat it does
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
write
Create a contact, optionally with channel identities.
update_contact(contact_id, name?, company?, city?, postcode?, external_id?, metadata?)contacts:write
write
Change a contact's details.
remove_contact_channel(contact_id, channel_id)contacts:write
destructive
Remove a channel identity from a contact.

Agents

ToolScopeWhat it does
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

ToolScopeWhat it does
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

ToolScopeWhat it does
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

ToolScopeWhat it does
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
write
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
write
Email a report on a schedule.
update_scheduled_export(export_id, name?, report_type?, schedule?, recipients?, format?, enabled?)reports:export
write
Change a scheduled export, or switch it on or off.
delete_scheduled_export(export_id)reports:export
destructive
Delete a scheduled export.

Notifications

ToolScopeWhat it does
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

ToolScopeWhat it does
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

ToolScopeWhat it does
suggest_reply(case_id, tone?, language?, area_instructions?, include_contact_history?, include_knowledge?, max_messages?, knowledge_top_k?)ai:invoke
write
Draft a reply to a case with the workspace's AI assistant. Nothing is sent.

Webhooks

ToolScopeWhat it does
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
write
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
write
Change a webhook endpoint, or switch it on or off.
send_test_webhook(webhook_id)webhooks:manage
write
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:

{"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 an agent can read directly when it 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

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:

{
  "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:

{
  "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):

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)

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"
DocumentContent
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-serverRFC 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

ResponseMeaning
HTTP 401Missing, invalid, revoked or expired token, or the OAuth client is deactivated. Fetch a new token.
HTTP 403 MCP_NOT_ENABLEDMCP access is not switched on for this workspace.
HTTP 403 ORIGIN_NOT_ALLOWEDA browser Origin that is not allowed.
HTTP 400Unsupported MCP-Protocol-Version, a body that is not JSON (-32700), or an empty or too large batch.
HTTP 405GET or DELETE on the endpoint; use POST.
HTTP 429Rate limit reached; wait for Retry-After.
HTTP 503 MCP_ACCESS_UNAVAILABLEThe workspace's MCP access could not be checked; retry after Retry-After (5 s). Access is never assumed.
JSON-RPC -32600Not a valid JSON-RPC 2.0 request.
JSON-RPC -32601Unknown method.
JSON-RPC -32602Unknown tool, or a tool the token's scopes don't allow (the message names the missing scope).
JSON-RPC -32603Internal error.
Tool result with isError: trueThe 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 the Security Policy and Data Processing Addendum.

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 fieldComes from the API operation
ScopesThe operation's OAuth2ClientCredentials security requirement
NameA pinned tool name, so names stay stable
Title and descriptionThe operation's summary and description
ArgumentsThe operation's path parameters, query parameters and JSON body
readOnlyHint / destructiveHintSet 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.

Ask us to enable MCP access