An AI client calling a Connect MCP tool
The client posts JSON-RPC to one endpoint, names a tool and its arguments, and receives a result. A workspace tool needs an integration key, and that key fixes the single workspace the call runs in. From there the call goes through the same domain service a person's click would, so autonomy, suppression, allowances and the audit trail all apply unchanged.
What the client actually does#
Connect implements the Model Context Protocol revision 2026-07-28 over Streamable HTTP: one endpoint, POST only. GET and DELETE answer 405. There are no protocol-level sessions in this revision — a session header is ignored and never minted, and event ids are ignored because streams are not resumable. Each request carries its protocol version and client identity in the request metadata, mirrored into headers; a header that disagrees with the body is refused rather than reconciled.
Clients speaking an older, initialisation-based revision are answered too. Refusing them would mean the connector directories of the day could not reach Connect at all, which defeats the purpose of publishing a server.
POST /mcp HTTP/1.1
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: list_followups
Authorization: Bearer <integration key>
{"jsonrpc":"2.0","id":7,"method":"tools/call",
"params":{"name":"list_followups","arguments":{"limit":10}}}The call, stage by stage#
- Trigger — a person asks their AI client a question, or an agent decides it needs data it does not hold.
- External event — the client sends one JSON-RPC request over HTTPS. Nothing has happened inside Connect yet.
- Authentication and workspace resolution — the integration key is resolved to exactly one workspace, and every later query is filtered to it. A browser Origin that is present and not allowed is answered 403 before anything else runs.
- Request — the method and the named tool are matched against the tool table; unknown method and unknown tool are different errors on purpose.
- Canonical record — nothing new is written for a read. A writing tool creates the same row the screen would create, through the service that owns it.
- Reasoning — none here. The server does not ask a model what a tool call means; the client already decided that.
- Knowledge, memory and rules — the tool reads the workspace's own data under the same isolation as a screen: allowlist, ORM kernel, then row-level security.
- Autonomy and approval — a writing tool is subject to the channel's autonomy mode. A send that would need a human yes becomes a held item rather than a message.
- Action through a service — the domain service runs. There is deliberately no tool that executes SQL, proxies an arbitrary internal route, or writes past the service that owns the record.
- Result — a JSON-RPC result, or a JSON-RPC error with a code the client can act on.
- Relationship, timeline and memory — anything the tool created lands on the person and the timeline exactly as it would from the application.
- Audit, usage and Needs You — the action is recorded with the key that made it, metered against the workspace's allowance, and queued for a person if it needs one.
What the key decides#
- Which workspace
- One. A key is issued inside a workspace and cannot address another; there is no workspace argument on any tool.
- Which tools
- Public documentation tools need no credential at all. Workspace tools are refused without a valid key.
- Who did it
- The audit entry names the key, so revoking a key and reading back what it did are both possible after the fact.
- What it cannot become
- A key is not a sign-in. It does not inherit a person's rights, and it cannot clear a do-not-contact entry.
Errors a client should expect#
| Situation | Shape | Client behaviour |
|---|---|---|
| Malformed JSON | JSON-RPC parse error | A bug in the client. Do not retry unchanged. |
| Unknown method | Method not found | Check the revision the client is speaking. |
| Unknown tool or bad arguments | Invalid params | Read the tool's input schema from tools/list rather than guessing. |
| Headers disagree with the body | A dedicated header-mismatch code | Send the metadata once, and mirror it exactly. |
| Browser Origin not allowed | HTTP 403 | An MCP client normally sends no Origin. A page in a browser is a different threat model. |
| GET or DELETE on the endpoint | HTTP 405 | This transport is POST only. |
Treat a 4xx as an answer. Retrying a refused call unchanged produces the same refusal and, on a writing tool, risks a duplicate if the first attempt actually succeeded and the response was lost. Where a tool supports an idempotency key, use it.
What this flow is not#
It is not a way around approval. If a workspace runs email in ask-before-send, a tool that composes a reply produces a held draft, and a person still releases it. An integration that appears to send instantly in one workspace and hold in another is showing you two autonomy settings, not two behaviours.
It is also not a bulk export. Tools are scoped, paged and metered; a data request from a customer is answered through its own flow.
Questions#
Does an MCP tool call bypass autonomy or suppression?
No, and that is the main design constraint on the server. Every workspace tool calls the same domain service the application calls, so autonomy modes, suppression, do-not-contact, allowance limits and the audit trail all apply. A tool that could bypass them would make the rules a workspace sets meaningless.
Why is there no session to open and close?
The protocol revision Connect implements removed protocol-level sessions. Each request stands alone and carries its own version and identity metadata. A client that opens a session and expects to reuse an identifier will find the identifier ignored rather than rejected.
Can one key read two workspaces?
No. The key resolves to one workspace and the filter is applied in three independent places, so a tool cannot return another workspace's rows even if a request tried to name one. If you operate several workspaces, issue a key in each.