Coevera MCP Server v2.0.9

Model Context Protocol (MCP) is an open standard that lets AI assistants (such as Claude, ChatGPT, or any MCP-compatible agent) call structured tools hosted on a remote server over HTTP. Instead of copy-pasting data into a chat window, the AI connects to this server and reads, searches, or updates CRM records directly.

This server implements the Streamable HTTP MCP transport. Requests are POSTed to the /mcp endpoint with a Bearer token. The AI model discovers what tools are available, then calls them with structured JSON arguments.

Long-running tool calls stream incremental progress notifications back to the client via Server-Sent Events (SSE). The client receives status messages such as "Fetching records…" and "Normalizing records…" before the final result, so the user sees live feedback instead of a blank wait. SSE is activated automatically when the client sends Accept: text/event-stream in the request (all MCP-compliant clients do this); clients that omit the header receive a plain JSON response.

Each MCP session is stateless — authentication is re-validated on every request via OAuth token introspection.

This server bridges AI assistants (such as Claude, ChatGPT, or any MCP-compatible agent) with the Coevera CRM. Instead of manually exporting data and pasting it into a chat window, the AI connects here and reads, searches, or updates CRM records directly using structured tool calls.

Typical workflows

1. Ask the AI to find all Accounts in Germany → calls search_records
2. Ask the AI to summarize open Opportunities → calls search_records + get_records
3. Ask the AI to create a follow-up Task for a Contact → calls create_records
4. Ask the AI to attach this PDF to the Contracts folder → calls upload_cloud_object_document, then POSTs the file to the returned upload_url
5. Ask the AI what fields does Lead have? → calls meta_describe_entity

Every MCP tool call follows this path from the AI assistant to the CRM and back:

Each request is fully stateless — no session is maintained between calls. The space_id tenant identifier is re-extracted from the token on every request.

All /mcp requests must carry an Authorization: Bearer <token> header. Tokens are obtained from the Coevera OAuth2 authorization server using the Authorization Code flow.

OAuth provider (CRM)

https://crm.coevera.com

Issuer (RFC 8414)

https://mcp-server.coevera.com  (this server — it serves the discovery documents, so the issuer must match its origin)

Authorization endpoint

https://crm.coevera.com/oauth2/app/authorize

Token endpoint

https://crm.coevera.com/oauth2/app/token

Introspection endpoint

https://crm.coevera.com/oauth2/app/introspection

Grant type

authorization_code

Auth methods

client_secret_basic, client_secret_post

Required scopes

OAuth discovery documents are served at /.well-known/oauth-authorization-server and /.well-known/openid-configuration.

CRM base URL

https://crm.coevera.com/

MCP endpoint

/mcp  (POST — requires Bearer token; returns SSE stream when client sends Accept: text/event-stream, plain JSON otherwise)

File upload

/upload/{token}  (POST multipart/form-data, field file — no Bearer header; the single-use token issued by upload_cloud_object_document is the credential. 410 if expired/used, 503 if upload store not configured)

Health check

/lbready  (GET — public)

This page

/doc  (GET — public)

OAuth discovery

/.well-known/oauth-authorization-server

OpenID config

/.well-known/openid-configuration

Protected resource

/.well-known/oauth-protected-resource

Every MCP tool declares four behavior hints so that AI clients (and their safety layers) can describe a tool's impact before it is called. Each hint is set explicitly — never null — and justified against the tool's actual behavior. The values below are the single source of truth: they are served verbatim in each tool's MCP definition.

The expand parameter on search_records and get_records loads related entities inline with each record instead of returning them as URL references. Use meta_describe_entity to find which relation fields support expansion (look for the expandable_fields array in the response).

Forms

Values must be non-empty lists — an empty list is rejected. Both forms can be combined in the same expand object.

Example — flat (single relation)

Returns only account_id and the nested account object (with id and name) for each item in account_relations.

{
  "account_relations": ["account_id", "account.id", "account.name"]
}

Example — flat + dotted (nested relation)

Expand product_relations with explicit sub-fields, and also expand the nested product object returning only name and id.

{
  "product_relations": ["id", "opportunity_id", "product_id"],
  "product_relations.product": ["name", "id"]
}

The filter parameter for search_records is a nested boolean tree. Leaf nodes map a field api_name to a comparator object.

Logical operators

Leaf comparators

Example

{
  "AND": [
    {"name": {"contains": ["Acme"]}},
    {"value": {"gte": "10000"}},
    {"OR": [
      {"status": {"eq": ["active"]}},
      {"close_date": {"null": true}}
    ]}
  ]
}

Only fields with filterable: true (returned by meta_describe_entity) can be used in filter expressions. Filterable types: string, int, date, datetime, uuid, enum.

MCP tool calls carry JSON, which makes them a poor fit for large binaries (base64 inflates the payload by a third and the whole file would have to pass through the LLM context). Uploads are therefore split into two phases: the MCP tool only registers the upload, and the file itself is sent by the client directly to a dedicated HTTP endpoint.

Client-side network allow-list. Phase 2 is an outbound HTTP request made from the AI client's own environment (its code-execution sandbox or connector runtime), not through MCP. Claude and ChatGPT restrict which hosts that environment may reach, so the domain *.coevera.com must be allowed in the client application's security / network settings before uploads work — see the app's preferences. If phase 1 succeeds but phase 2 never reaches the server (no POST /upload/… in the logs), this is the first thing to check.

Example

// Phase 1 — MCP tool call
upload_cloud_object_document({
  "document": {
    "filename":  "contract.pdf",
    "mime_type": "application/pdf",
    "folder_id": "0195d175-7d96-e9c2-40fb-d0c793886f92",
    "is_public": false
  }
})
// → {"cloud_object_id": "…", "upload_token": "…", "upload_url": "https://mcp-server.coevera.com/upload/…",
//    "expires_in_seconds": 300, "max_file_bytes": 52428800, "max_file_mib": 50}

// Phase 2 — plain HTTP, from the client's environment
curl -X POST "https://mcp-server.coevera.com/upload/<upload_token>" -F file=@contract.pdf
// → {"createCloudObject": {"cloudObject": {"id": "…", "filename": "contract.pdf", "size": 48213, "url": "…", "publicUrl": null, …}}}

Upload endpoint responses

Security properties

• The token is 256 bits of secrets.token_hex randomness — unguessable — and is deleted on first use, so a leaked URL cannot be replayed.
• The bearer token is encrypted at rest in Redis (upload_token_encryption_key); a Redis dump does not yield live CRM credentials.
• Phase 2 runs under the original caller's identity and space, so CRM permissions and tenant isolation apply exactly as for any other tool.
• /upload/* is exempt from BearerAuthMiddleware by design — the one-time token replaces the bearer header for that single request.

Server configuration

The tool is only registered as usable when a Redis upload store is configured. All keys live in config/defaults.py (override via environment / config/local.yml):

The server uses a two-stage rate limiter: a short-window burst limit per token and a longer-window sustained limit per space (tenant). When either limit is hit, the server returns 429 Too Many Requests.

• Check the Retry-After response header for the recommended back-off duration.
• The server retries Coevera CRM API calls internally (up to 5 times, 30 s apart) before surfacing a 503.
• Prefer batching: pass multiple IDs to get_records rather than making one call per record.

• Start with meta_list_entity_types — if that fails, the problem is auth or connectivity, not filter syntax.
• Use meta_describe_entity to confirm exact api_name values before passing fields to search_records or get_records.
• Only fields with filterable: true (returned by meta_describe_entity) can appear in filter expressions.
• The /lbready endpoint is public and returns 200 OK when the server is running — use it to confirm reachability before debugging authentication.
• OAuth discovery documents at /.well-known/oauth-authorization-server and /.well-known/openid-configuration are also public and can confirm the correct token / introspection endpoints.