> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fitsociety.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connection & Protocol

> Connect to the hardened FITsociety MCP transport and negotiate a supported protocol version.

The FITsociety MCP runtime is served at:

```txt theme={null}
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:

```http theme={null}
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:

```http theme={null}
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.

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](/mcp/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.

```http theme={null}
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.

## 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.

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.