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

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

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

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