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| 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:
- 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. - 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
| Tool | Scope | What it does |
|---|---|---|
list_cases(status?, channel?, area_id?, agent_id?, contact_id?, priority?, query?, cursor?, limit?, offset?, sort_by?, sort_dir?) | cases:readread-only | List the workspace's cases (conversations), newest first unless sorted otherwise. |
get_case_stats() | cases:readread-only | Case counts for the workspace (by state, channel and so on). |
get_case(case_id) | cases:readread-only | Get one case. |
get_case_history(case_id, limit?, offset?) | cases:readread-only | The case's event history (state changes, assignments, forwards). |
list_case_messages(case_id, limit?, offset?) | cases:readread-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:writewrite | Open a new case, optionally with its first message. |
update_case(case_id, subject?, priority?, channel?, state_label?, due_date?, metadata?) | cases:writewrite | Change a case's subject, priority, channel, state label, due date or metadata. |
acquire_case(case_id) | cases:writewrite | Take ownership of a case. |
return_case(case_id, reason?) | cases:writewrite | Give a case back to its queue. |
forward_case(case_id, forward_type, target_id?, target_address?, include_history?, reason?) | cases:writewrite | Forward a case to another area, agent, team leader, external address or workflow. |
close_case(case_id, note?) | cases:writedestructive | Close a case. |
reopen_case(case_id) | cases:writewrite | 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:writewrite | 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:writedestructive | Close several cases at once. |
bulk_tag_cases(case_ids, tag_ids?, tag_names?) | cases:writewrite | 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:writewrite | Forward several cases at once. |
Contacts
| Tool | Scope | What it does |
|---|---|---|
list_contacts(limit?, offset?) | contacts:readread-only | List the workspace's contacts (customers). |
search_contacts(channel?, identifier?, external_id?, name?, email?, phone?, q?, limit?) | contacts:readread-only | Find contacts by channel identity, external id, name, email, phone or free text. |
get_contact(contact_id) | contacts:readread-only | Get one contact with their channel identities. |
get_contact_history(contact_id) | contacts:readread-only | The contact's past cases. |
list_contact_notes(contact_id) | contacts:readread-only | Notes kept on a contact. |
create_contact(name?, company?, city?, postcode?, external_id?, metadata?, channels?) | contacts:writewrite | Create a contact, optionally with channel identities. |
update_contact(contact_id, name?, company?, city?, postcode?, external_id?, metadata?) | contacts:writewrite | Change a contact's details. |
remove_contact_channel(contact_id, channel_id) | contacts:writedestructive | Remove a channel identity from a contact. |
Agents
| Tool | Scope | What it does |
|---|---|---|
list_agents(status?, role?, group_id?, is_active?, cursor?, limit?) | agents:readread-only | List the workspace's agents. |
get_agent(agent_id) | agents:readread-only | Get one agent's profile. |
get_agent_stats(agent_id) | agents:readread-only | One agent's workload and performance figures. |
get_agent_skills(agent_id) | agents:readread-only | The skills assigned to an agent. |
get_presence_board() | agents:readread-only | Who is online, busy or away right now. |
get_agent_presence(agent_id) | agents:readread-only | One agent's current presence. |
Knowledge base
| Tool | Scope | What it does |
|---|---|---|
list_knowledge_articles(limit?, offset?) | knowledge:readread-only | List the knowledge base articles. |
get_knowledge_article(article_id) | knowledge:readread-only | Get one knowledge base article. |
search_knowledge(query, area_id?, language?, top_k?) | knowledge:readread-only | Semantic search over the knowledge base. |
answer_from_knowledge(query, area_id?, language?, top_k?, include_sources?, case_id?) | knowledge:readread-only | Get an answer to a question, written from the knowledge base articles. |
Routing
| Tool | Scope | What it does |
|---|---|---|
list_routing_rules(limit?, offset?) | routing:readread-only | List the rules that route incoming messages to areas. |
get_routing_rule(rule_id) | routing:readread-only | Get one routing rule. |
list_routing_groups(limit?, offset?) | routing:readread-only | List the routing groups (sets of areas). |
get_routing_group(group_id) | routing:readread-only | Get one routing group. |
Reports
| Tool | Scope | What it does |
|---|---|---|
list_report_types() | reports:readread-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:readread-only | Run a report over a period and return its rows. |
ask_report_question(question, context?) | reports:readread-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:readread-only | Reports that are emailed on a schedule. |
get_scheduled_export(export_id) | reports:readread-only | Get one scheduled export. |
create_report_export(report_config, format) | reports:exportwrite | Start a file export of a report. Poll get_report_export until it is done. |
get_report_export(job_id) | reports:exportread-only | Status of a report export. |
get_report_export_download(job_id) | reports:exportread-only | A download link for a finished report export (returned as download_url). |
create_scheduled_export(name, report_type, schedule, recipients, format) | reports:exportwrite | Email a report on a schedule. |
update_scheduled_export(export_id, name?, report_type?, schedule?, recipients?, format?, enabled?) | reports:exportwrite | Change a scheduled export, or switch it on or off. |
delete_scheduled_export(export_id) | reports:exportdestructive | Delete a scheduled export. |
Notifications
| Tool | Scope | What it does |
|---|---|---|
list_notification_templates() | notifications:readread-only | The workspace's notification templates. |
get_notification_template(template_id) | notifications:readread-only | Get one notification template. |
Usage
| Tool | Scope | What it does |
|---|---|---|
get_current_usage() | metering:readread-only | Usage in the current billing period. |
get_usage_history(date_from, date_to, action?, channel?, granularity?) | metering:readread-only | Usage over a period, bucketed by time. |
get_usage_breakdown(date_from, date_to) | metering:readread-only | Usage over a period, broken down by action and channel. |
get_ai_vs_human_usage(date_from, date_to) | metering:readread-only | How much work AI handled compared with agents, over a period. |
get_usage_summary(date_from, date_to) | metering:readread-only | Usage totals over a period. |
AI assist
| Tool | Scope | What it does |
|---|---|---|
suggest_reply(case_id, tone?, language?, area_instructions?, include_contact_history?, include_knowledge?, max_messages?, knowledge_top_k?) | ai:invokewrite | Draft a reply to a case with the workspace's AI assistant. Nothing is sent. |
Webhooks
| Tool | Scope | What it does |
|---|---|---|
list_webhooks(limit?, offset?) | webhooks:manageread-only | Webhook endpoints registered for this workspace. |
get_webhook(webhook_id) | webhooks:manageread-only | Get one webhook endpoint. |
list_webhook_deliveries(webhook_id, limit?, offset?) | webhooks:manageread-only | Recent delivery attempts to a webhook endpoint. |
create_webhook(url, events, description?) | webhooks:managewrite | 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:managewrite | Change a webhook endpoint, or switch it on or off. |
send_test_webhook(webhook_id) | webhooks:managewrite | Send a synthetic test event to the webhook endpoint. |
delete_webhook(webhook_id) | webhooks:managedestructive | 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
limitandoffset(or thecursorfrom 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.jsonConfigure 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"| 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
:readscopes gets only read-only tools;cases:write,contacts:write,reports:export,webhooks:manageandai:invokeadd 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
Originare 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 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.