> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwiflow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote MCP

> Connect an existing agent environment to hosted Kiwi through OAuth or a project-bound MCP key.

Kiwi provides a hosted Streamable HTTP MCP connection at the path /mcp. The signed-in app's setup helper gives you the complete canonical endpoint for your project. OAuth protected-resource metadata is available at /.well-known/oauth-protected-resource/mcp on the same host. Use the endpoint from the helper; do not guess or type a host.

For the default setup path, select the intended organization in Kiwi, then open **Set up your agent → Copy setup prompt** from [Projects home](https://www.kiwiflow.io/app) or the global [MCP & access page](https://www.kiwiflow.io/app/mcp). Choose the project inside the helper. See [Set up your agent](https://docs.kiwiflow.io/ai-quickstart.md) for account, invitation, and client-connection steps.

## Connect with OAuth

OAuth is the usual setup for an existing agent client. In that client's MCP settings, add a remote server with the URL copied from Kiwi's setup helper and use OAuth sign-in. The access token must target the exact /mcp resource and include the user:org:read scope. Select the organization that contains the intended project in the sign-in flow.

Use the configuration controls supported by your agent client. If the client stores MCP settings in a file, follow that client's own instructions and keep credentials in its credential store. The agent client connects directly to the hosted endpoint.

## Project-bound MCP keys

For a client that supports a static Authorization header, a project Admin can open **MCP & access**, select one project, choose read-only or workflow-write access, and issue an expiring key. Send its one-time secret as a Bearer token:

```http theme={null}
Authorization: Bearer YOUR_MCP_KEY
```

Read-only keys can call read tools. Workflow-write keys can also start runs and report ordinary agent step progress. Both are restricted to one project and the issuer's current project grant. They cannot make human decisions, manage organization settings, or submit checker-origin results. A checker key cannot authenticate to MCP.

The key secret is returned only once. Issuance replay does not reveal it again or create a replacement. If the one-time secret is lost, revoke that key in Kiwi and issue a new one.

## Available tools

Discover the current tool list in your MCP client after connecting. The hosted service supports these tools; argument names are camelCase.

| Tool | Purpose and inputs |
| - | - |
| list\_projects | No arguments. Lists projects available to the authenticated user. A static key sees only its bound project. |
| list\_workflows | projectId, optional offset and limit. Lists published definitions, revisions, digests, and pagination totals. Defaults to offset 0 and limit 50; maximum limit 100. |
| list\_connections | projectId. Lists active nonsecret references and exact workflow-step bindings. |
| start\_run | projectId, commandId, workflowId, optional workflowRevision, requestText or requestReference, optional responsibleUserId, designatedOwnerId, and designatedReviewerId, plus declared harness/session fields. Creates a pinned run and initial graph. |
| get\_run | runId and declared harness/session fields. Reads the current actor-specific run projection and event cursor. |
| start\_step | runId, stepId, commandId, positive expectedRunVersion, attemptId, and declared harness/session fields. Starts an eligible attempt. |
| submit\_result | The start\_step fields plus outputs. Submits ordinary step outputs; it cannot submit human decisions or Verify results. |
| report\_blocker | The start\_step fields plus reason. Records a resumable blocker for that owned attempt. |
| handoff\_step | The start\_step fields plus a new nextAttemptId and notes. Queues the same step for the run's responsible human. |
| list\_skills | projectId. Lists the authorized skill library. |
| get\_profile | projectId, profileId, version. Reads exact published safe profile settings. |
| get\_assignment | Explicit run/step/optional child assignment and harness/session. Reads its pinned work contract and current context. |
| get\_step\_skill | Explicit run/step or child, exact skill/version, and harness/session. Delivers bound instructions and their file/dependency manifest. |
| get\_skill\_file | The same assignment and exact skill/version plus path. Delivers a referenced text file. |
| create\_assignment | Current parent attempt, run version, command ID, designated project member, scope, and pinned skill. Records bounded delegated work. |
| start\_assignment | Child assignment, current run version, command ID, and harness/session. Claims the assigned task. |
| submit\_assignment | Child assignment, current run version, command ID, outputs, and harness/session. Records evidence without accepting the parent. |
| report\_configuration | Current owned attempt or child, run version, command ID, and safe exposed settings. Appends an attributed report. |
| report\_skill\_use | Current owned attempt or child, run version, command ID, and declared skill/version use. Keeps claims separate from pins. |
| create\_skill\_check | projectId, exact draft/release target, command ID, and optional workflow context. Creates a persisted remote checker job. |
| run\_skill\_check | projectId, job ID, and command ID. Runs a bounded remote review; pending retries retain the same job. |
| get\_skill\_check | projectId and job ID. Reads status and the retained report history. |

For workflow-skill versions, assignment instructions, and remote checks, see [Workflow skills and execution records](https://docs.kiwiflow.io/workflow-skills.md). For the step order, output shape, human pauses, and retry rules, follow the [Agent guide](https://docs.kiwiflow.io/for-agents.md). For CI check reports, use a checker credential and [CI reporting](https://docs.kiwiflow.io/ci-reporting.md).

## MCP responses and errors

Successful tool calls return structuredContent as well as a text content item containing the same JSON. A run mutation returns an updated run projection and receipt. get\_run returns a run projection and eventCursor; it does not return a full event list. The receipt identifies the command, whether it was recorded or replayed, the new run version and cursor, and the recorded event.

A simplified get\_run response has this shape:

```json theme={null}
{
  "run": {
    "runId": "00000000-0000-4000-8000-000000000000",
    "projectId": "00000000-0000-4000-8000-000000000001",
    "status": "active",
    "version": 1,
    "candidate": null,
    "candidateRevision": 0,
    "planRevision": 0,
    "graph": [
      {
        "stepId": "plan",
        "name": "Plan",
        "status": "ready",
        "allowedActorKinds": ["human", "agent"],
        "eligibleRoles": ["admin", "contributor", "reviewer"],
        "requiredOutputs": [
          { "name": "scope", "type": "text" },
          { "name": "acceptance_criteria", "type": "text-list" },
          { "name": "required_checks", "type": "check-definition-list", "minimum_items": 1 }
        ],
        "acceptance": { "mode": "human_decision", "assignee": "designated_owner" },
        "currentAttemptId": null,
        "attempts": []
      }
    ],
    "checkResults": [],
    "nextActions": ["start_step"]
  },
  "eventCursor": 1
}
```

Identifiers and versions above are illustrative. MCP errors return isError: true and a JSON text content item with error and message. If a mutation may have reached Kiwi but its response is missing, retry the identical command with the same payload. A successful MCP tool call does not establish acceptance of a workflow step or run.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.