MCP endpoint

A coach can point an MCP client, such as an AI assistant, at Perform and let it search trainees, assign plans and create tasks. The endpoint needs nothing installed: a URL and a studio API key. Mount: /mcp, outside /v1. Router mcpRouter in src/modules/mcp/mcp.routes.ts, mounted in src/app.ts behind the same rate limiter instance as /v1. Tool definitions live in the package @perform/mcp-tools (backend/packages/mcp-tools/src/tools.ts), which a stdio build of the server shares. Production URL: https://perform-api.otherwise.co.il/mcp

How it works

The endpoint is a stateless MCP server over Streamable HTTP, built with @modelcontextprotocol/sdk.

Each POST /mcp request builds a new McpServer named perform (version 1.0.0) and a new StreamableHTTPServerTransport with no session id generator. There is no session, no stream to resume and no affinity between requests.
Every tool from @perform/mcp-tools is registered with its Zod input schema and annotations (readOnlyHint from the tool, destructiveHint: false, openWorldHint: true).
When a tool is called, the handler does not touch the database. It builds an HTTP request and sends it to /v1/automation on the same process, at http://127.0.0.1:<PORT>/v1/automation, with the caller’s own API key.
The automation lane’s data is returned to the model as pretty-printed JSON text. An error from the lane is returned as a tool result with isError: true and the lane’s message as text.

That extra local hop is deliberate. The MCP surface cannot drift from the public API, and tool calls inherit the automation lane’s validation, studio scoping, audit log and readable error sentences. Everything on Automation API applies to the matching tool.

Authentication

Send a studio API key as a bearer token. It is the same key used for the automation and partner lanes, created by an OWNER or HEAD_COACH. See Partner API for key management.

POST /mcp HTTP/1.1
Host: perform-api.otherwise.co.il
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json, text/event-stream

The router itself only checks that a bearer value is present and starts with pf_live_. The key is really verified when a tool makes its call to /v1/automation. So a well-formed but invalid key can connect and list tools, and every tool call then fails with invalid partner api key. A typical client configuration:

{
  "mcpServers": {
    "perform": {
      "url": "https://perform-api.otherwise.co.il/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

The exact configuration format depends on the MCP client.

Endpoints

`POST /mcp`

Handles one MCP JSON-RPC message: initialize, tools/list, tools/call and the rest of the protocol the SDK implements. Auth: studio API key. The body is a JSON-RPC 2.0 message. The response is JSON-RPC, as JSON or as a server-sent event stream, depending on what the transport negotiates with the client’s Accept header. Listing tools:

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

Calling a tool:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": { "name": "find_trainee_by_phone", "arguments": { "phone": "0500000000" } }
}

A successful tool result carries the automation lane’s data as text:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"found\": true,\n  \"trainee\": {\n    \"id\": \"cm2k9x1ab0001l508u3f7q2wd\",\n    \"name\": \"Noa Cohen\"\n  }\n}"
      }
    ]
  }
}

A failed tool call is still a JSON-RPC success, with the error inside the result so the model can read it and recover:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "No trainee with id cm000 exists in this studio. Use \"Search trainees\" or \"Find trainee by phone\" to get a valid id."
      }
    ]
  }
}

Errors:

Status	Body	When
401	JSON-RPC error `-32600` with a message explaining how to create a key, plus a `WWW-Authenticate: Bearer` header	No bearer value, or one that does not start with `pf_live_`
429	The rate limiter’s default response	The global limit is exceeded
500	JSON-RPC error `-32603` `Internal server error`	The server or transport threw before a response was sent

`GET /mcp`

Not supported. The server is stateless, so there is no stream to open. Response: 405.

{ "jsonrpc": "2.0", "error": { "code": -32600, "message": "This server is stateless; use POST." }, "id": null }

No other method is registered on /mcp.

Tools

The tool set is limited on purpose. A model acts without a person approving each step, so anything that destroys data or reaches a trainee’s phone is left out. The comment at the top of tools.ts lists what is excluded: deleting a trainee, sending a message, freezing a plan and cancelling a plan. Webhooks are not exposed either.

Read tools

Tool	Automation endpoint	Input
`search_trainees`	`GET /v1/automation/trainees/search`	`q`, `status`, `coachId`, `tag`, `createdAfter`, `updatedAfter`, `limit`, `offset`
`find_trainee_by_phone`	`GET /v1/automation/trainees/by-phone/:phone`	`phone`
`get_trainee`	`GET /v1/automation/trainees/:id`	`traineeId`
`list_trainee_programs`	`GET /v1/automation/trainees/:id/programs`	`traineeId`
`list_trainee_form_responses`	`GET /v1/automation/trainees/:id/form-responses`	`traineeId`, `limit`, `offset`
`list_trainee_weights`	`GET /v1/automation/trainees/:id/weights`	`traineeId`, `limit`, `offset`
`list_trainee_subscriptions`	`GET /v1/automation/trainees/:id/subscriptions`	`traineeId`
`list_plans`	`GET /v1/automation/products`	`search`, `limit`, `offset`
`list_program_templates`	`GET /v1/automation/program-templates`	`search`, `limit`, `offset`
`list_forms`	`GET /v1/automation/forms`	`search`, `limit`, `offset`
`list_coaches`	`GET /v1/automation/rpc/coaches`	None
`list_tags`	`GET /v1/automation/rpc/tags`	None
`list_tasks`	`GET /v1/automation/tasks`	`status`, `clientId`, `coachId`, `limit`, `offset`

limit is 1 to 200 and offset is 0 or more on every tool that takes them.

Write tools

Tool	Automation endpoint	What the tool forces
`create_trainee`	`POST /v1/automation/trainees`	`sendWhatsappInvite: false`. It also sends `notify: false`, which the create schema does not define and drops
`update_trainee`	`PATCH /v1/automation/trainees/:id`	Nothing. `tags` and `coachIds` replace the stored lists
`assign_plan`	`POST /v1/automation/trainees/:id/subscription`	`notify: false`
`assign_program`	`POST /v1/automation/trainees/:id/programs/assign`	`notify: false` and `replaceExisting: false`, so a retry fails with a clear conflict instead of stacking a duplicate
`send_form`	`POST /v1/automation/trainees/:id/forms/assign`	Nothing. `notify` is passed through with its three states, and `fieldValues` is accepted for documents to sign
`create_task`	`POST /v1/automation/tasks`	Nothing
`update_task`	`PATCH /v1/automation/tasks/:id`	Nothing
`log_weight`	`POST /v1/automation/trainees/:id/weights`	Nothing

Tool inputs are validated twice: by the tool’s own Zod schema in the MCP layer, then by the automation lane’s schema. Tool schemas use real JSON types (numbers, booleans, arrays), not the string coercion Make needs. send_form with notify: true is the one tool that can push a notification to a trainee’s device straight away. A PDF_SIGNATURE form sends nothing and returns a signing link for the coach to deliver.

Limits and operations

Rate limit. /mcp uses the same limiter instance as /v1: 120 requests per 60 seconds per IP by default (RATE_LIMIT_MAX, RATE_LIMIT_WINDOW_MS).
Internal calls are also limited. A tool call makes a second request to /v1/automation from 127.0.0.1. That request passes through the same limiter keyed by its own source address, so tool calls from every MCP user share the loopback address’s bucket. Under heavy combined use, tool calls can be throttled even when each client is under its own limit.
Body size. The global 24 MB JSON limit applies.
Audit. Writes are recorded in AuditLog by the automation lane with the API key id as the actor. Nothing marks an entry as having come through MCP.
Revoking access. Revoke the API key. The next tool call fails.
Logging. A failure inside the handler is logged as mcp request failed.

Adding a tool

Add the endpoint to the automation lane first, with its schema, service function and readable errors.
Add a ToolDefinition to backend/packages/mcp-tools/src/tools.ts: name, title, description, readOnly, a Zod inputSchema and a call function that returns the method, path and body.
Decide what the tool must force. Anything that notifies a trainee should default to silent.

No change is needed in mcp.routes.ts. It registers every tool in the exported list.

API basics

Trainees

Plans and libraries

Tracking

Imports

Forms

Tasks and automation

Communication

Studio and billing

Admin and internal services

Trainee app API

Partner and automation

Public, internal and auth

How it works

Authentication

Endpoints

`POST /mcp`

`GET /mcp`

Tools

Read tools

Write tools

Limits and operations

Adding a tool

​How it works

​Authentication

​Endpoints

​POST /mcp

​GET /mcp

​Tools

​Read tools

​Write tools

​Limits and operations

​Adding a tool

How it works

Authentication

Endpoints

`POST /mcp`

`GET /mcp`

Tools

Read tools

Write tools

Limits and operations

Adding a tool