MCP server and mcp-tools

Perform exposes a studio’s data to AI clients through the Model Context Protocol. There are two transports and one tool set.

Piece	Location	Transport
Tool definitions and HTTP client	`packages/mcp-tools` (`@perform/mcp-tools`)	none, a library
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
WhatsApp agent	`modules/agent/agent.llm.ts`	uses the same tool set in process

All three execute a tool the same way: an HTTP call to the automation API (/v1/automation) with a studio API key. One key means one studio, so every tool is already scoped and cannot reach another studio’s data.

Why tools call HTTP on the same process

The hosted endpoint builds its client with baseUrl set to http://127.0.0.1:<PORT>/v1/automation. That loopback hop is deliberate:

The MCP surface cannot drift from the public API, because it is the public API.
Tool calls inherit the automation lane’s key check, validation and error wording.
The lane’s errors are written as sentences that say what to do next, which is exactly what a model needs to correct itself.

`@perform/mcp-tools`

`tools`

tools: ToolDefinition[] is the single list every transport registers.

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 };
};

A tool does not perform the request. call maps validated input to a method, a path under /v1/automation and an optional body. The transport makes the request. That keeps tools pure and testable.

Read tools

Tool	Automation route
`search_trainees`	`GET /trainees/search`
`find_trainee_by_phone`	`GET /trainees/by-phone/:phone`
`get_trainee`	`GET /trainees/:id`
`list_trainee_programs`	`GET /trainees/:id/programs`
`list_trainee_form_responses`	`GET /trainees/:id/form-responses`
`list_trainee_weights`	`GET /trainees/:id/weights`
`list_trainee_subscriptions`	`GET /trainees/:id/subscriptions`
`list_plans`	`GET /products`
`list_program_templates`	`GET /program-templates`
`list_forms`	`GET /forms`
`list_coaches`	`GET /rpc/coaches`
`list_tags`	`GET /rpc/tags`
`list_tasks`	`GET /tasks`

List tools share limit (1 to 200, default 50 on the server) and offset.

Write tools

Tool	Automation route	Forced fields
`create_trainee`	`POST /trainees`	`sendWhatsappInvite: false`, `notify: false`
`update_trainee`	`PATCH /trainees/:id`
`assign_plan`	`POST /trainees/:id/subscription`	`notify: false`
`assign_program`	`POST /trainees/:id/programs/assign`	`notify: false`, `replaceExisting: false`
`send_form`	`POST /trainees/:id/forms/assign`	none. `notify` is the caller’s choice
`create_task`	`POST /tasks`
`update_task`	`PATCH /tasks/:id`
`log_weight`	`POST /trainees/:id/weights`

create_trainee takes an externalId. Models retry, and with that set a repeat call returns the trainee that already exists. onDuplicatePhone can be return_existing or update.

Scope limits

The header comment in tools.ts states the rule. A model acts without a human checking each step, so anything that destroys data or reaches a real person is left out.

Not exposed	Reason
Delete a trainee	Erases their whole history. Irreversible.
Send a message	Pushes to a real person’s device.
Freeze a plan	Fires a `SUBSCRIPTION_FROZEN` push that cannot be suppressed.
Cancel a plan	Ends someone’s paid subscription.

Assigning a plan or a program can notify, so those tools force notify: false. WhatsApp invites are never sent from MCP. Those actions exist on /v1/automation for callers that decide to use them. They are not offered to a model. Every tool is registered with destructiveHint: false, openWorldHint: true and readOnlyHint from the definition.

`createPerformClient`

const client = createPerformClient({ apiKey, baseUrl? });
await client.request('GET', '/trainees/search?q=dana');
await client.validate(); // { studioName, slug }

baseUrl defaults to the production automation URL.
request sends Authorization: Bearer <apiKey>, parses the automation envelope and returns data.
A non 2xx response or success: false throws PerformApiError with the lane’s message and the HTTP status. A network failure throws with status 0. A non JSON body throws with the first 200 characters.

Errors are passed through as text on purpose. Do not reshape them into codes.

The hosted endpoint

POST /mcp in mcp.routes.ts.

Reads Authorization: Bearer. A missing key or one without the pf_live_ prefix answers 401 with WWW-Authenticate: Bearer realm="Perform", error="invalid_token" and a JSON-RPC error body. MCP clients read that header to work out how to authenticate.
Builds a createPerformClient with the key and the loopback URL.
Creates a new McpServer named perform and registers every tool.
Creates a StreamableHTTPServerTransport with no session id generator, which puts it in stateless mode.
Connects and calls transport.handleRequest(req, res, req.body).
Closes the transport and the server when the response closes.

Stateless means every request builds its own server and transport. There is no session affinity and nothing to keep alive. GET /mcp answers 405 with This server is stateless; use POST. The prefix check in step 1 is only a shape check. The real validation happens when the first tool call reaches /v1/automation and requirePartnerKey looks the key up. A tool failure is returned to the model as a tool result with isError: true and the message as text. A failure in the transport itself is logged as mcp request failed and answered with JSON-RPC error -32603. /mcp is behind the /v1 rate limiter, keyed by IP.

Connecting a client

A coach creates an API key in the web app under Business settings, Integrations. The key is shown once.

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

The stdio binary

apps/mcp-server/src/index.ts is the same registration loop over StdioServerTransport.

Variable	Required	Purpose
`PERFORM_API_KEY`	yes	The studio API key. Missing exits with code 1 and an explanation on stderr.
`PERFORM_API_URL`	no	Overrides the automation base URL. Defaults to production.

On startup it calls client.validate() and logs the studio it connected to on stderr. A bad key fails at startup instead of on the first tool call, so the model never has to diagnose a setup problem. stdout is reserved for the protocol.

pnpm --filter @perform/mcp-server build

{
  "mcpServers": {
    "perform": {
      "command": "node",
      "args": ["/absolute/path/to/backend/apps/mcp-server/dist/index.js"],
      "env": { "PERFORM_API_KEY": "YOUR_API_KEY" }
    }
  }
}

The file reads process.env directly and disables the lint rule for it. It runs on a coach’s machine and must not pull in the server’s config schema, which demands a database.

Adding a tool

Make sure the automation route exists

A tool is a view of an automation API route. Add the route first if it is missing, with sentence style error messages.

Check it against the scope rules

If it deletes data, sends something to a trainee or ends a subscription, do not add it. If it can notify, force the silent option in call.

Add the definition

Append a ToolDefinition to tools in packages/mcp-tools/src/tools.ts. Write description for a model: say when to use it, what to call first to get ids, and what a retry does. Add .describe() to every input field, with units.

Rebuild

pnpm --filter @perform/mcp-tools build. The hosted endpoint, the binary and the WhatsApp agent pick it up from the shared list.

Testing

The mcp-server README describes two end to end suites that run against a live API and clean up after themselves (a temporary key and a temporary trainee, both deleted): one for the hosted endpoint over HTTPS and one that spawns the stdio binary and drives it over real MCP. Run them only against an environment where creating and deleting a trainee is acceptable.

​Why tools call HTTP on the same process

​@perform/mcp-tools

​tools

​Read tools

​Write tools

​Scope limits

​createPerformClient

​The hosted endpoint

​Connecting a client

​The stdio binary

​Adding a tool

​Testing