# The MCP server.

How a coding agent works with Perfloop, and the tools a member can call.

Updated 28 September 2026.

## Connect

The server is at `https://app.perfloop.ai/mcp`. It requires a login: the agent signs in with your Perfloop account, and your role in the workspace decides what it can read or change. There is no anonymous access. Add Perfloop to your agent, then sign in — every agent Setup offers, with the same steps Setup gives:

### Claude Code

```
claude mcp add --transport http perfloop https://app.perfloop.ai/mcp
```

Open Claude Code, run /mcp, choose perfloop, and sign in.

### Cursor

```
{
  "mcpServers": {
    "perfloop": {
      "url": "https://app.perfloop.ai/mcp"
    }
  }
}
```

Save this as ~/.cursor/mcp.json, then open Settings → Tools & MCP and authenticate perfloop.

### Codex

```
codex mcp add perfloop --url https://app.perfloop.ai/mcp --oauth-resource https://app.perfloop.ai/mcp
codex mcp login perfloop
```

Codex opens your browser to finish the Perfloop sign-in.

### OpenCode

```
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "perfloop": {
      "type": "remote",
      "url": "https://app.perfloop.ai/mcp"
    }
  }
}
```

Add this to opencode.json, then run opencode mcp auth perfloop.

### Pi

```
{
  "mcpServers": {
    "perfloop": {
      "url": "https://app.perfloop.ai/mcp"
    }
  }
}
```

Pi needs the pi-mcp-adapter extension. Run pi install npm:pi-mcp-adapter, save this as .mcp.json, reload Pi, then run /mcp-auth perfloop.

### Amp

```
amp mcp add perfloop https://app.perfloop.ai/mcp
```

Restart Amp and complete the OAuth flow it opens in your browser. OAuth MCP is not supported in Amp Orbs.

For automation with nobody present, a member API key with `read,contribute` stands in for the login. Add `admin` to that key when the automation reads Usage or changes workspace setup.

## What the agent can do

Reads return the model, cases, Initiatives, the Inbox, Usage, and submissions, in bounded pages. Writes start or stop Sessions, file feedback, decide Inbox items, and change an Initiative's direction. Every write is recorded under the authenticated user or API key. The server cannot record a result, and it cannot approve or merge a pull request.

Admins can allow a public HTTPS path or its exact host from the Inbox. Approved destinations have no count limit. Manage the complete list in Setup under Network access. Removing a destination blocks the next matching read unless another destination still covers it. The Inbox keeps at most 100 network requests per workspace. At capacity, new requests replace decided rows first, then the oldest pending request whose requesting Session has ended. A live Session can request a removed destination again. Removal grants no access.

## Model building

Call `model` with `section: "buildStatus"`, then call `buildModel` to start one Session. It accepts:

- `modelSeq` (required): the model sequence returned in that build status. The build records the live model sequence at start; a stale value does not reject the request.
- `repoID` (optional): the repo to build. Omit it to let Perfloop choose the next repo.
- `focus` (optional, requires `repoID`): an exact repo-relative `path` to a source file or directory. Add `name` for a case-sensitive source name as written under that path, such as `Server.serve`. The build stops with a named gap if the name is not written there.
- `patternSlugs` (optional, requires `repoID`): active pattern slugs from the catalog. Omit it for a broad build. An empty list, repeated slug, or unavailable pattern is rejected.

For example, use your model sequence and replace `repo_…` with your repo ID:

```
{
  "modelSeq": 7,
  "repoID": "repo_…",
  "patternSlugs": [
    "identity_collision",
    "resource_leak"
  ]
}
```

With selected patterns, the Session reuses fresh mapping or maps first, then hunts for each pattern over the related paths. Completed work is reused; unfinished work stays pending. Normal Session limits apply. The result reports this bounded attempt, not coverage of the whole repo. Autonomous model building does not need to be enabled.

## Tools

What each tool is for, grouped by what you do with it; your agent reads each tool's inputs from the server itself. These can start a paid Session: `approve`, `submitIdea`, `workCase`, `buildModel`, and `startResearch`; the rest start none. Tools only a workspace admin can call are not listed here; the catalog marks them. Every docs page, this one included, is also a resource on the server, so an agent can read it without leaving the session.

To read a Case's timeline or attempts, pass its `caseID` and the `section`. Add `sessionID` for one Session, or `candidateID` for one attempt. A redundant `first` on an exact read is ignored. To page the attempts, pass the previous `candidateIndex.pageInfo.endCursor` as `after`; a row number is not a cursor.

Once a Session ends, its row in the timeline carries `sessionResult` and `sessionEndedAt`. A Session that stopped early also carries `sessionStopReason`, a fixed code such as `case_session_stalled` or `controller_replaced` that says why.

A Case summary and its `hypothesis` section return the hypothesis's `forecast`. The model's `hypotheses` section returns it too: `size` (S, M, L, XL, or unknown), `reason`, `sourceChanged`, and `evidence` artifact IDs. The forecast is null when no assessment is available. `sourceChanged: true` means the source differs from the assessment's saved source basis. A false value can be inconclusive when that basis is missing. Private guidance references are not returned.

### See the work

- **`cases`** List the Cases in your workspace, or read one: its hypothesis, the evidence, each attempt, the feedback on it, and the code it changed.
- **`model`** Read the model Perfloop keeps of your system, one part at a time: its repos, services, workloads, and paths, the patterns and hypotheses on them, and whether a build is running.
- **`initiatives`** List the Initiatives, with the workspace research cadence, or read one: its scope, its sources, its research runs, and its Cases.
- **`inbox`** Read what waits for a decision, newest first: a short list, or one item in full.
- **`submission`** Read what became of an idea a coding agent submitted: admitted as a Case, or why not.

### Steer it

- **`fileFeedback`** File feedback on a Case for the next Session to act on; it also holds publication until someone rules that the change passes or approves publication over it. That pass settles open member feedback and carries no direction, so file it only when no direction remains. It starts no work.
- **`editInitiative`** Replace an Initiative's title, outcome, rationale, disposition, and scope, as one new version.
- **`closeCase`** Close a Case with a reason. A Session already running keeps going until you stop it.
- **`reopenCase`** Reopen a Case you closed. It starts no work.

### Decide what waits in the Inbox

- **`approve`** Approve what an Inbox item proposes, exactly as shown. When that is work, this starts it.
- **`reject`** Reject a proposal with a reason.
- **`resolve`** Close a Case whose pull request still waits for approval, because it was handled another way. Give the reason; no pull request opens.
- **`decidePRClosure`** When a pull request Perfloop opened was closed without a merge and Perfloop could not decide, say whether the Case closes or continues with another approach.

### Start and stop work

- **`submitIdea`** Propose a hypothesis from your coding agent: what should change, in which file, and why. Perfloop starts a Session to check it against the model, and admits it as a Case or records why not.
- **`workCase`** Start a Session on a Case, or start one again on a Case that waits for a person.
- **`buildModel`** Build the model of a repository, or bring it up to date. You can point the next pass at one file or directory, or at one name in it.
- **`startResearch`** Start a research Session on an Initiative, or create the Initiative from an outcome, a rationale, and a repository and start its first one. While the workspace cadence is on, an active Initiative keeps getting research Sessions on that cadence, each one paid, until you pause or settle it or turn the cadence off.
- **`setResearchCadence`** Set how often research runs on its own, one cadence for the whole workspace. It starts no Session itself: a cadence above zero authorizes recurring paid research Sessions on each active Initiative after its first one, and zero stops them.
- **`stopSession`** Stop a running Session, whatever it is doing: Case work, a model build, an idea being checked, or research.

Also in this section: [The loop](https://perfloop.ai/docs/work), [Case states](https://perfloop.ai/docs/work/states), [Steering and learning](https://perfloop.ai/docs/work/steering), [Initiatives](https://perfloop.ai/docs/work/initiatives), and [Autonomy and limits](https://perfloop.ai/docs/work/autonomy).

Questions: [hello@perfloop.ai](mailto:hello@perfloop.ai?subject=Perfloop%20docs)