Skip to main content
The FITsociety MCP runtime is served at:
The server 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. Consent requests are single-use and expire after 10 minutes. Users who need to sign in can do so and then resume the same request. Approval 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 server supports the modern 2026-07-28 protocol and the listed 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 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 discovery and request metadata as described above.

Usage guidance in tool definitions

Every tools/list tool description includes the configured shared request allowances and query budget, retry timing, account/consent scope, and error-result handling. Each tool also states its business-read or write requirements and, where applicable, query cost, pagination bounds, date-range bounds, confirmation fields, and delivery or destructive effects. Existing domain-specific details and input/output schemas remain part of the tool definition. This guidance is included in the plain description field, so a function-calling client that forwards the tool’s name, description, and input schema to its model can make it visible without forwarding initialization instructions, HTTP headers, or metadata. Forward the descriptions when converting MCP tools to model tools. Refresh the tool list after a server update to obtain current guidance. Request and query quotas are shared across tools. Listing a capability does not grant access to it; account, company, module, action and consent checks still apply. Business-read tools do not require write grants or write idempotency keys. Their calls are still recorded in connection activity.

Complete catalog discovery

Use https://mcp.fitsociety.io/mcp/v1?catalog=all to discover 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. 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; requests for only client_ai_* scopes go straight to the client sign-in. Clients sign in on the central FITsociety connect page with their client email and password, choose one of their companies, and then review permissions. Companies where AI connections are not possible stay visible with the reason, for example when AI is turned off at that company. Clients who use Google or Microsoft sign-in can still continue through their own portal address. Coaches choose the company on the consent page, which switches their active company. Both account types use the existing 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.
An exact retry with the same key returns the completed result without applying the change again. Missing or invalid write keys are rejected before tool execution.

Request limits

MCP requests are limited to 1 MB for JSON bodies and 64 KB for URL-encoded bodies. Requests must use the supported server host and an allowed browser Origin when one is supplied.

Request rate

The default allowances are 120 requests per minute per credential and 240 requests per minute per IP address. The credential allowance is shared across tools and protocol requests, including initialization and discovery. Requests from the same IP share its allowance across credentials. Attempts and retries count toward the request allowance. Windows reset at each minute boundary. The MCP initialization and discovery instructions state the configured limits. Deployments may use different limits; use the returned instructions and response headers for the active quota. When a request is rate limited, the server returns HTTP 429 with JSON-RPC error code -32029 and message COMPANY_MCP_RATE_LIMITED. The error’s data contains the applied scope, limit, remaining, windowSeconds, retryAfterSeconds, and a human-readable reason. Pause requests for the returned delay.

Tool query budget

Tool execution also shares a separate default budget of 120 units per minute per connection grant. A read costs 1 unit plus 1 unit per started block of 25 items in its requested pagination limit; a write costs 5 units. This budget can therefore reject a tool call before the transport request allowance is exhausted. Completed write replays do not consume additional query budget. Budget rejections return COMPANY_MCP_QUERY_BUDGET_EXCEEDED with a retryAfterMs delay in milliseconds. Tool calls may also be temporarily unavailable after repeated failures. See Troubleshooting & Errors for retry guidance.

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.