MCP server

What the server is

A JSON-RPC dispatcher in front of the operation registry. A tool call resolves to the operation the tool was generated from and runs it as the authenticated actor, so an agent and the web UI cannot see different behaviour.

initialize answers with instructions written for whoever authenticated the session — your handle, your model, and the reminder to check your scopes before proposing. Tool schemas are the operation's schemas: path parameters, query and body flattened into one input object.

Connecting a client

Use the same /mcp endpoint whether the client authenticates with a long-lived agent key or a delegated OAuth connection.

claude mcp add --transport http trunk https://app.trunk.dev/mcp \
  --header "Authorization: Bearer $AGENT_KEY"

[mcp_servers.trunk]
url = "https://app.trunk.dev/mcp"
bearer_token_env_var = "TRUNK_API_KEY"

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "trunk": {
      "type": "remote",
      "url": "https://app.trunk.dev/mcp",
      "enabled": true,
      "headers": { "Authorization": "Bearer {env:TRUNK_API_KEY}" }
    }
  }
}

OAuth-capable remote MCP clients, including ChatGPT, should be pointed at https://app.trunk.dev/mcp and let MCP/OAuth discovery drive registration and authorization. They do not need a pre-created Trunk agent key; see Remote OAuth clients below.

Every message is a POST to https://app.trunk.dev/mcp. A notification — a message with no id — is answered 202 with no body, as JSON-RPC requires. Both transports run the same dispatcher; mcp.json carries the stdio command for a checkout you run yourself.

Authentication

HTTP MCP accepts either an existing Trunk bearer credential or a delegated OAuth bearer issued specifically for the /mcp protected resource.

• An agent API key identifies that existing Trunk agent directly. Ordinary repository and source reads use their tenant/repository boundaries; agent scopes constrain operations that explicitly check scoped authority, while budget and track record feed proposal and policy behaviour where those operations use them.
• A delegated OAuth bearer is different: Trunk creates or reuses a keyless integration agent for the consenting human, organization and OAuth client. The bearer is valid for the /mcp resource, not as general /v1 API authority.
• A handle is not a credential. Over the network that would let anyone be any agent, so a key, session, or valid delegated OAuth bearer must resolve to an authenticated actor.
• Without valid authority the HTTP endpoint rejects the request before dispatching a tool call. Over stdio the server still starts, but every tools/call fails until a credential is present.

Remote OAuth clients

For remote clients that support MCP OAuth, Trunk uses discovery plus Authorization Code with PKCE and explicit human consent instead of asking the user to copy an agent key into the client.

1. Point the client at https://app.trunk.dev/mcp. Trunk publishes OAuth protected-resource and authorization-server metadata, so a compatible client can discover the authorization, token, registration and revocation endpoints. Public clients may use dynamic client registration.
2. Sign in and consent in Trunk. The authorization flow is Authorization Code with PKCE. Trunk shows the organization and requested delegated capabilities before issuing authority to the client.
3. Read authority starts narrow. trunk:mcp:read is the required base OAuth scope. Its complete audited tool surface is trunk_whoami, trunk_list_repos, trunk_get_repo, trunk_log, trunk_list_branches, trunk_list_source, trunk_read_source, trunk_read_sources, trunk_search_source, trunk_preflight_patch and trunk_stats. It does not imply access to the rest of the generic MCP read catalog. Delegated OAuth also exposes only the trunk://me MCP resource; trunk://queue and trunk://policy remain generic API-key/session MCP resources.
4. Change recovery is separate. trunk:mcp:changes:read adds exactly trunk_list_changes and trunk_get_change. Delegated list results contain only id, repo_id, branch, revision, base_commit and status. Delegated get accepts the Change id without the generic include selector and adds only the exact stored diff. Generic Change risk, reported results, author presentation, evidence, trace, decisions and track data are not delegated by this scope.
5. Proposal authority is separate too. trunk:mcp:propose adds exactly trunk_propose_change and trunk_mark_change_ready; it does not inherit the consenting human's owner/admin authority. The delegated integration agent still needs its own current Trunk repository/service/path proposal scope for either authoring mutation. It may propose Draft or non-Draft work, and only the exact author may mark its exact current Draft revision Ready. Ready removes only that author-controlled hold; it does not grant direct landing authority. An authorized proposal may still automatically land through the normal Change lifecycle when the integration agent's scope and budget, repository policy and required checks allow it.
6. There is no separately delegated direct-land authority. OAuth does not expose trunk_land_change, force-land, revert, verification, scope-granting or other human/provider control-plane operations. Automatic landing after trunk_propose_change or exact-author Ready is a policy outcome, not a delegated land operation. A new OAuth scope added by Trunk also does not silently widen an already-issued token; additional authority requires fresh consent.

Request offline_access only when the client needs refresh tokens. Trunk rotates refresh tokens: a successful refresh immediately makes the presented refresh token unusable and returns one successor. Reusing that predecessor while it is still within its accepted lifetime is treated as replay and retires only that refresh-token family; after the predecessor expires it is simply invalid. For signed credentials, revoking a family-bound access token or a refresh token likewise retires that family, while other independently issued token families on the same active delegation grant survive. Public-client revocation requests include their client_id; a mismatched client or unknown token remains an idempotent, non-disclosing revocation result. An access-only token has no refresh family, so revoking it retires the grant generation instead. Losing the delegating human's organization membership also retires the delegation grant, so credentials derived from that grant no longer authenticate.

Protocol methods

What the dispatcher answers. Anything else comes back as -32601.

What comes back

A tool result is one text block holding the operation's JSON response. Two things are worth knowing before you parse it.

• Proposals are summarised. trunk_propose_change returns the routing decision rather than the whole evidence bundle: the change id and status, whether it landed, the risk score and band, the rule that decided it, the findings above info with their file and line, and what to do next. Whentrunk_get_change is available, it reads back the Change view allowed for the current credential; delegated OAuth Change-read authority intentionally returns only recovery fields plus the exact stored proposal diff.
• Failures are results, not transport errors. A rejected call comes back with isError: true and the message, so the session survives it.

Tools

The catalog below is the full generic MCP tool surface, with each operation and input shape. It is not an OAuth grant manifest: delegated OAuth clients see only the audited base-read tools above plus separately consented Change-readback or proposal tools.

Resources

The catalog below is the full generic API-key/session MCP resource surface. Delegated OAuth exposes only trunk://me; trunk://queue and trunk://policy are not delegated OAuth resources.

Not tools, on purpose

These operations exist on the API and are reachable by a person, but no general agent-facing tool grants them. Registering identities, widening credentials and approving evidence are human acts.