Connection & Protocol - FITsociety Developer APIs

The FITsociety MCP runtime is served at:

https://mcp.fitsociety.io/mcp/v1

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:

GET /.well-known/oauth-protected-resource/mcp/v1

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:

GET /.well-known/oauth-authorization-server

It publishes the authorization, token, and dynamic client registration endpoints together with authorization-code, refresh-token, and PKCE S256 support.

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.

POST /mcp/v1 HTTP/1.1
Host: mcp.fitsociety.io
Authorization: Bearer <credential>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: start_workout_session

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:

Method	Purpose
`initialize`	Negotiate a supported legacy protocol version and obtain server capabilities.
`notifications/initialized`	Confirm legacy initialization.
`ping`	Check runtime connectivity.
`tools/list`	List only the tools visible to the approved grant.
`tools/call`	Execute one visible tool.
`resources/list`	Return an empty resource list.
`prompts/list`	Return an empty prompt list.

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.

Write idempotency

Every write tool call must include a unique key in params._meta.idempotencyKey. The key may be reused only for an exact replay of the same operation.

{
  "jsonrpc": "2.0",
  "id": "workout-write-1",
  "method": "tools/call",
  "params": {
    "name": "start_workout_session",
    "arguments": {
      "clientId": "64b64c0f2f5f4c0012345678"
    },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {},
      "idempotencyKey": "workout-session-64b64c0f-2026-08-10"
    }
  }
}

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.

​Discovery

​Runtime transport

​Initialization and tools

​Write idempotency

​Transport protections

​Health check