Remote MCP

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 or the global MCP & access page. Choose the project inside the helper. See Set up your agent 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:

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. For the step order, output shape, human pauses, and retry rules, follow the Agent guide. For CI check reports, use a checker credential and CI reporting.

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:

{
  "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.

Start

Use Kiwi

Connect agents and CI

Help

Connect with OAuth

Project-bound MCP keys

Available tools

MCP responses and errors

​Connect with OAuth

​Project-bound MCP keys

​Available tools

​MCP responses and errors

Connect with OAuth

Project-bound MCP keys

Available tools

MCP responses and errors