Skip to main content
The FITsociety MCP runtime is served at:
The runtime uses the official @modelcontextprotocol/server v2 handler. It supports modern MCP 2026-07-28 and stateless legacy requests for 2025-11-25, 2025-06-18, 2025-03-26, and 2024-11-05.

​
Discovery

Use the path-specific RFC 9728 protected-resource metadata document:
The root discovery path redirects permanently to that document. The response identifies https://mcp.fitsociety.io/mcp/v1 as the protected resource and advertises bearer credentials in the HTTP header only. OAuth authorization-server metadata is available at:
It publishes the authorization, token, and dynamic client registration endpoints together with authorization-code, refresh-token, and PKCE S256 support. The authorization endpoint does not forward OAuth parameters to the consent page. It stores each validated authorize request as a single-use server-side transaction (valid for 10 minutes) and redirects the user to the consent page with only an opaque transaction id, so the consent flow survives an intervening login — users who still need to sign in resume the same request afterwards. Approval consumes the transaction exactly once and redirects back to the client’s registered callback with the authorization code and original state. See Authentication for the full flow.

​
Runtime transport

Send JSON-RPC requests to POST /mcp/v1. Always include the bearer credential in the Authorization header; credentials in query parameters or request bodies are not accepted.
The official transport negotiates the modern 2026-07-28 protocol and adapts the supported legacy versions in stateless mode. JSON-RPC batch requests are not supported. Modern 2026-07-28 requests include MCP-Protocol-Version: 2026-07-28 and a matching Mcp-Method header. Named operations such as tools/call also include Mcp-Name. Each request carries io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities in its params._meta envelope. Legacy clients omit that modern envelope and negotiate through initialize. GET /mcp/v1 is delegated to the same official transport handler. It is not a compatibility SSE stream and clients must not use it as a handshake endpoint.

​
Initialization and tools

Legacy clients initialize through JSON-RPC and then use the standard tool methods: Modern MCP 2026-07-28 clients use the official v2 transport’s discovery and request metadata. Do not emulate modern requests with an older custom JSON-RPC adapter.

​
Complete catalog for review

Use https://mcp.fitsociety.io/mcp/v1?catalog=all when a client, including the ChatGPT submission portal, needs a fixed catalog containing both coach and client tools. Authentication is still required. This mode returns all tool names, schemas, and annotations; it does not expand the connection’s permissions. Every call is checked against the authenticated account’s role, company, modules, write actions, and data consent. Calls outside that access are rejected before business execution. The URL without this query keeps the usual scoped discovery. The OAuth resource identifier remains https://mcp.fitsociety.io/mcp/v1. When OAuth requests both account types or omits scopes, choose coach or client before signing in. Clients enter their own FITsociety company portal address. Both choices use the existing authenticated consent and revocation flows.

​
Write idempotency

Every write tool call must include a unique idempotencyKey in its arguments or in params._meta.idempotencyKey. The argument is available for clients such as ChatGPT that supply tool arguments but do not set custom request metadata. If both locations are supplied, their values must match. The key may be reused only for an exact replay of the same operation.
The runtime persists the completed response before returning it. A retry with the same key replays that durable result instead of running the mutation again. Missing or invalid write keys are rejected before tool execution.

​
Transport protections

Before authentication or tool execution, the runtime validates the request IP before parsing, bounds parsed MCP requests to 1 MB JSON and 64 KB URL-encoded bodies, and applies persistent limits for request IPs and bearer-key identifiers. The official transport then validates Host and, when present, Origin against configured allowlists. Authenticated execution additionally uses a persistent per-grant query budget and persistent per-company/tool circuit state. When a required limiter, circuit state, idempotency record, or audit write is unavailable, the runtime fails closed rather than continuing without that protection. The generic audit record is durably persisted before the official transport response is returned.

​
Health check

GET /mcp/v1/health is a separate authenticated diagnostic endpoint. It uses the same bearer-header authentication and returns the resolved grant context; it is not part of MCP transport negotiation.