MCP server - Perform

Perform exposes a studio’s trainees, plans, programs, forms and tasks as Model Context Protocol tools. A coach connects an AI client with their studio API key and can ask questions or make small changes in plain language. There are two servers and one shared tool set.

Piece	Location	Transport
Tool definitions and HTTP client	`packages/mcp-tools` (`@perform/mcp-tools`)	n/a
Hosted endpoint	`apps/core-api/src/modules/mcp/mcp.routes.ts`, mounted at `/mcp`	Streamable HTTP, stateless
Local binary	`apps/mcp-server` (`@perform/mcp-server`, bin `perform-mcp`)	stdio

The WhatsApp AI assistant uses the same tool definitions. See WhatsApp webhooks and the agent.

One rule: tools call the automation lane

No tool touches the database. Each tool is a description of one HTTP call to /v1/automation:

export type ToolDefinition = {
  name: string;
  title: string;
  description: string;
  readOnly: boolean;
  inputSchema: z.ZodObject<z.ZodRawShape>;
  call: (input: ToolInput) => { method: string; path: string; body?: unknown };
};

createPerformClient({ apiKey, baseUrl }) in packages/mcp-tools/src/client.ts executes it with Authorization: Bearer and unwraps the automation envelope. The hosted endpoint does this as a loopback request to http://127.0.0.1:<PORT>/v1/automation on the same process. That extra hop costs microseconds and buys three things:

The MCP surface and the public API can never drift apart.
Every MCP call gets the lane’s validation, plan limits and audit logging unchanged.
Errors are the lane’s readable sentences, for example “No trainee with id X exists in this studio. Use Search trainees to get a valid id.” That is what a model needs to recover on its own, so failures are passed through as text and not reshaped into codes.

One key is one studio, so every tool is already scoped. There is no way to reach another studio’s data.

Hosted endpoint

POST /mcp
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Production URL: https://perform-api.otherwise.co.il/mcp. A coach pastes the URL and their key into an MCP client. Nothing to install.

Authentication

The handler checks that the header is a bearer token starting with pf_live_. If not, it answers 401 with a JSON-RPC error and a WWW-Authenticate: Bearer realm="Perform", error="invalid_token" header, which MCP clients read to work out how to authenticate. The message tells the user where to create a key. The key itself is not verified at this point. It is verified by the automation lane on the first tool call, so a well-formed but wrong key connects, lists tools, and then fails each call with “invalid partner api key”. There is no OAuth flow. Authentication is the static studio API key. See Partner API and API keys.

Stateless by design

Every request builds its own McpServer and its own StreamableHTTPServerTransport. Omitting sessionIdGenerator is what puts the transport in stateless mode. Consequences:

No session affinity. The endpoint scales with the API.
GET /mcp answers 405 with “This server is stateless; use POST.” There is no stream to resume and no session to delete.
The server and transport are closed when the response closes.

Rate limit and errors

/mcp is mounted in app.ts with the same global limiter as /v1: RATE_LIMIT_MAX requests per RATE_LIMIT_WINDOW_MS. Each tool call also makes one loopback request to /v1/automation, which passes through the limiter again. An unexpected failure answers 500 with JSON-RPC error code -32603. A tool failure is not a transport error: it returns isError: true with the message as text content.

Annotations

Each tool is registered with readOnlyHint from its readOnly flag, destructiveHint: false and openWorldHint: true. No tool deletes data or messages a trainee, so none is destructive.

Local binary

apps/mcp-server/src/index.ts is the same tool set over stdio, for clients that launch a local process.

Variable	Required	Purpose
`PERFORM_API_KEY`	yes	The studio API key. The process exits with a message when it is missing.
`PERFORM_API_URL`	no	Base URL of the automation lane. Defaults to production.

Example client configuration:

{
  "mcpServers": {
    "perform": {
      "command": "perform-mcp",
      "env": { "PERFORM_API_KEY": "YOUR_API_KEY" }
    }
  }
}

It reads process.env directly on purpose. It runs on a coach’s own machine with two variables and must not pull in the server’s config schema, which demands a database and the full API environment. client.validate() calls GET /validate and returns the studio name and slug.

What is deliberately left out

The scope is reads plus “soft” writes. A model acts without a human watching each step, so anything that destroys data or reaches a real trainee’s phone is not a tool:

Not exposed	Why
Delete a trainee	Erases their whole history. Irreversible.
Send a message	Pushes to a real person’s device.
Freeze a plan	Fires a push that cannot be suppressed.
Cancel a plan	Ends someone’s paid subscription.
WhatsApp invites	Never sent from here.

Writes that can notify are forced silent in the tool’s call:

Tool	Forced body values
`create_trainee`	`sendWhatsappInvite: false`, `notify: false`
`assign_plan`	`notify: false`
`assign_program`	`notify: false`, `replaceExisting: false`

A coach opting into notifications is a decision for the app, not for a model. send_form is the exception: it passes notify through, because the default (the hourly notifier announces the form once) is already the gentle path.

Tools

21 tools: 13 read-only and 8 writes. Paths are relative to /v1/automation.

Read-only

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

limit is 1 to 200 with a default of 50. offset starts at 0.

Writes

Tool	Call	Input
`create_trainee`	`POST /trainees`	`firstName`, `lastName`, `phone` (required), `email`, `birthDate`, `gender`, `heightCm`, `weightKg`, `goal`, `stepsGoal`, `tags`, `coachIds`, `productId`, `startedOn`, and more
`update_trainee`	`PATCH /trainees/:id`	`traineeId`, then any of the profile fields. `tags` and `coachIds` replace the whole list.
`assign_plan`	`POST /trainees/:id/subscription`	`traineeId`, `productId`, `startedOn`, price and duration overrides
`assign_program`	`POST /trainees/:id/programs/assign`	`traineeId`, `templateId`, `startsOn`
`send_form`	`POST /trainees/:id/forms/assign`	`traineeId`, `formTemplateId`, `dueAt`, `prompt` (up to 500), `notify`, `fieldValues`
`create_task`	`POST /tasks`	`title` (required), `clientId`, `detail` (up to 2000), `dueAt`, `priority` (0 to 5), `coachId`
`update_task`	`PATCH /tasks/:id`	`taskId`, `status`, `snoozeUntil`, `priority`
`log_weight`	`POST /trainees/:id/weights`	`traineeId`, `weightKg` (up to 500), `recordedAt`

create_task is the right way for a model to tell a coach to do something. It does not reach the trainee. Tool descriptions are written for the model. They say when to use the tool, where ids come from (“From list_plans”), and what null means on a plan’s price and duration.

The assign_plan tool describes startedOn as defaulting to today. The API does something else when it is omitted: the new plan starts when the trainee’s last live plan ends. The API behaviour is what happens. The tool description is out of date.

Which tools the WhatsApp assistant gets

AGENT_TOOLS in apps/core-api/src/modules/agent/agent.llm.ts is a subset:

export const AGENT_TOOLS = mcpTools.filter((t) => t.readOnly || t.name === 'create_task');

Every read, plus create_task. The other writes change a trainee’s world from a chat message and wait for a confirmation step before they are worth the risk.

Adding a tool

Make sure the automation lane can do it

A tool is only a call to /v1/automation. If the endpoint does not exist, add it there first, with its Zod schema and readable error messages.

Add the definition

Append to tools in packages/mcp-tools/src/tools.ts. Describe every input with .describe(). Set readOnly honestly, because the WhatsApp assistant’s tool list is derived from it.

Decide what the model may not control

If the endpoint can notify a trainee, force the flag off in call. Do not expose it as an input.

Rebuild the package

@perform/mcp-tools is consumed through its built output by the hosted endpoint, the local binary and the assistant. A new tool appears in all three after a rebuild and deploy.

There are end-to-end scripts for both transports under packages/database/scripts: mcp-http-e2e.mts and mcp-server-e2e.mts.

​One rule: tools call the automation lane

​Hosted endpoint

​Authentication

​Stateless by design

​Rate limit and errors

​Annotations

​Local binary

​What is deliberately left out

​Tools

​Read-only

​Writes

​Which tools the WhatsApp assistant gets

​Adding a tool

One rule: tools call the automation lane

Hosted endpoint

Authentication

Stateless by design

Rate limit and errors

Annotations

Local binary

What is deliberately left out

Tools

Read-only

Writes

Which tools the WhatsApp assistant gets

Adding a tool