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: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:
state.
See Authentication for the full flow.
Runtime transport
Send JSON-RPC requests toPOST /mcp/v1. Always include the bearer credential
in the Authorization header; credentials in query parameters or request bodies
are not accepted.
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
Everytools/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
Usehttps://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 uniqueidempotencyKey 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.
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 browserOrigin 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 returnCOMPANY_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.