MCP server and client profile
MCP server and client profile for Q integrations.
Q's qualified MCP endpoint is POST /v1/mcp, using Streamable HTTP and the official Python SDK 1.27.0. Supported revisions are 2025-03-26, 2025-06-18 and 2025-11-25; 2025-11-25 is preferred. This is the q-mcp-2025 profile. It does not implement the 2026-07-28 per-request metadata protocol.
Connect and discover
Use a provisioned Q bearer token or API key on every request, with the same authentication and scope rules as REST. Send a valid initialize, retain the returned MCP-Session-Id, then send notifications/initialized. Later requests include that session ID and the negotiated MCP-Protocol-Version. The official SDK handles these steps. The working Python example discovers tools and calls search using environment credentials.
POST accepts one JSON-RPC message with Content-Type: application/json and Accept: application/json, text/event-stream. Requests return JSON or a request-scoped SSE stream; accepted notifications return 202 without a body. GET returns 405: there is no standalone SSE or replay stream. DELETE terminates a session. A 404 requires a new handshake; it does not authorise replaying an uncertain tool call.
/.well-known/mcp-server-card is Q-specific discovery metadata. The public capability registry and the card expose whether the deployment enables the profile. tools/list further filters tools against the current credential scopes. Q advertises only tools, with no list-change notification promise.
| Tools | Required scope | Result |
|---|---|---|
q_search, q_space_search, q_list_spaces | ai:search | Web search, authorised knowledge passages, owner-visible spaces |
q_ask, q_research | ai:answer | Grounded answer text and applicable sources |
q_create_document, q_create_presentation, q_create_pack | ai:answer | Draft text, slide outline, pack plan |
q_list_skills | ai:answer | Published agent skill metadata |
Draft tools return content, not uploaded artefacts. Billing mutations, resources, Apps, prompts, sampling, elicitation and protocol task augmentation are outside this profile. Use durable runs for jobs which must survive disconnects or restarts. Tools enforce their returned JSON schemas: non-empty text up to 16,000 characters, result limits 1–50, and no extra argument fields. Tenant, owner, scopes and budgets come from authentication, never tool arguments or client metadata. March 2025 clients receive JSON text; later clients also receive structured results.
Completion, cancellation and errors
An SSE connection is not a completed tool call. Wait for the matching JSON-RPC result and inspect isError. Unknown tools/invalid parameters use protocol error -32602; unavailable methods use -32601; malformed JSON uses -32700. Tool failures use isError=true with a stable code and retryable=false. Provider exception text and input contents are not exposed. Q auth/admission failures may instead use the unified Q error envelope; OpenAPI describes both shapes.
Send notifications/cancelled with the original request ID to cancel a running call. Cancellation remains available under execution saturation. Cancellation is scoped to the authenticated session. The default tool deadline is 120 seconds and work also observes shared request/tool/provider capacity and spending limits. A disconnect alone is not a durable completion signal or proof that work stopped. Reconcile uncertain effects through the original tool invocation or run; never assume a new call is safe.
Q as a client
Register the exact remote MCP endpoint URL, such as https://service.example/mcp. Q uses the SDK transport through the common DNS/address/credential policy, with no redirects or tool POST retries. Both JSON and SSE are parsed by the SDK. Paginated discovery stops after 20 pages or 1,000 definitions and rejects cursor cycles. Q sends cancellation when an interrupted operation can still reach the remote endpoint; remote acknowledgement is not guaranteed. Remote isError results are failures. Tenant evidence requires Q's explicit ACL envelope in result _meta; data without the permission contract is rejected. Remote resources are always re-read and reauthorised: old content-only resource caches are bypassed because they cannot prove current permissions.
Discovery is request-scoped. Each tool/resource operation owns a fresh SDK connection, so session task lifetimes and credentials cannot cross operations. This includes an extra handshake; pooling is not yet qualified. Existing outbound byte/time limits still apply (8 MiB and a 60-second transport ceiling), even when a caller requests a longer tool timeout. Legacy /mcp/v1/initialize or per-method URLs, stdio and the old two-endpoint SSE transport are not supported by this adapter.
Deployment and migration
MCP_SERVER_PROFILE_ENABLED defaults to false; disabled calls return 503 and discovery advertises no enabled tools. This deliberately replaces the old custom beta endpoint. Migrate batch requests into individual messages, supply the full handshake and preserve headers. Do not enable the replacement until existing consumers have been inventoried and qualified.
Configure MCP_SERVER_ALLOWED_ORIGINS as a comma-separated exact allowlist for browser clients. An absent Origin is allowed; any present Origin must match. Require TLS and normal Q authentication. Defaults: 256 sessions per worker, 32 per tenant and 8 per principal, 900-second idle lifetime, 64 KiB request body, 1 MiB tool result and 120-second tool deadline. Settings are MCP_SERVER_MAX_SESSIONS, MCP_SERVER_TENANT_SESSIONS, MCP_SERVER_PRINCIPAL_SESSIONS, MCP_SERVER_SESSION_SECONDS, MCP_SERVER_MAX_BODY_BYTES, MCP_SERVER_MAX_RESULT_BYTES and MCP_SERVER_CALL_SECONDS. Deploy with session affinity to the owning worker; arbitrary multi-worker routing is not qualified. Restarts discard sessions, not durable run history. Keep session IDs out of logs and share them only with the authorised client.
Local tests use synthetic services and official SDK clients/servers. Production enablement additionally requires proxy/TLS/Origin/affinity tests, current dependency audit, representative load, real provider/ACL qualification and prior spending rollout gates. See ADR 0029.