withHuman MCP server

The withHuman MCP server lets a coding agent or assistant configure withHuman on your behalf. Connect Claude, Claude Code, Cursor, Codex or any other MCP client with one of your API keys, and ask it in plain language: "send every refund over $500 to the payments team and approve the rest." The agent reads your agents, members and teams, creates the escalation path, writes the pipeline, and can test a sample request before it goes live.

This is a different thing from the MCP Gateway. The gateway sits between an agent and the external tools it calls, and asks for approval. The MCP server is how an agent manages withHuman's own settings. On hosted withHuman the CLI adds the gateway to your agents as withhuman-gateway, so it never takes the withhuman name you give this server.

flowchart LR
    you["You, in your agent's chat"] -->|"Set up refund approvals"| agent["Coding agent or assistant"]
    agent -->|"Sign in and choose permissions, once"| consent["withHuman in your browser"]
    consent --> agent
    agent -->|MCP tools| server["withHuman MCP server"]
    server --> pipelines["Approval pipelines"]
    server --> paths["Escalation paths"]
    server --> teams["Teams"]
    server --> agents["Agents"]
    server --> webhooks["Webhook endpoints"]

Connecting

The server's address is your deployment's origin followed by /api/mcp/v1. On hosted withHuman it is https://app.withhuman.ai/api/mcp/v1. Both API keys pages in Settings show the address and a ready-made command for Claude Code. Add the server to your client as a streamable HTTP server:

claude mcp add --transport http --scope user withhuman https://app.withhuman.ai/api/mcp/v1

/mcp

codex mcp add withhuman --url https://app.withhuman.ai/api/mcp/v1

codex mcp login withhuman

{
  "mcpServers": {
    "withhuman": {
      "url": "https://app.withhuman.ai/api/mcp/v1"
    }
  }
}

There is no key to copy. The first time the agent talks to withHuman, it opens your browser at the consent page. You sign in if you are not already, see which agent is asking and which organization you are connecting it to, choose what it may do, and choose whether the access lasts 90 days or until you revoke it. Approving sends you back to the agent, which is connected from then on.

Approving creates a personal API key named after the agent, marked Connected agent in your key list. Revoking that key disconnects the agent; it will ask you to connect again the next time it needs withHuman. When the access expires, the agent asks you to connect again in the same way.

Without a browser

A headless integration that cannot open a browser can send an existing personal or organization API key as a bearer token instead. Put the key in the WITHHUMAN_API_KEY environment variable and add the server with the header:

claude mcp add --transport http --scope user withhuman https://app.withhuman.ai/api/mcp/v1 \
  --header "Authorization: Bearer $WITHHUMAN_API_KEY"

codex mcp add withhuman --url https://app.withhuman.ai/api/mcp/v1 \
  --bearer-token-env-var WITHHUMAN_API_KEY

{
  "mcpServers": {
    "withhuman": {
      "url": "https://app.withhuman.ai/api/mcp/v1",
      "headers": {
        "Authorization": "Bearer ${env:WITHHUMAN_API_KEY}"
      }
    }
  }
}

A browser session never opens the server, so a link in a page cannot act as you.

What the agent can do

The agent gets tools for the same things the pages in Settings do:

Saving a pipeline, escalation path, team escalation policy, webhook endpoint or gateway server creates a new revision and activates it in the same step, so the change applies right away. The agent can save a draft instead and leave activation to you. Earlier revisions stay available for rollback, exactly as in the app; see Immutability.

A credential, provisioner token or webhook signing secret the agent creates appears once, in the agent's chat. Pass it to whoever configures the service and don't leave it in shared transcripts.

Deciding requests, inviting people, giving someone a role or permission policy, and connecting a gateway scope through OAuth always need a signed-in person in the app, as do creating and revoking API keys. To connect a coding agent to withHuman, use the withhuman CLI; see Instance connections.

Permissions

The agent can do exactly what you allow it on the consent page: everything you can do, or only the actions you tick. Either way it follows your permissions as they change, and it can never do more than you. For example, an agent allowed to edit pipelines but not activate them leaves drafts for you to activate in the app. Granting an action that can decide requests or is marked dangerous asks for a recent sign-in, like creating such a key by hand. Choosing specific actions is available in the hosted edition; elsewhere the agent gets everything you can do.

An organization key used as a bearer token can build pipelines, escalation paths, webhook endpoints and gateway servers, manage agents and read the audit log, but cannot manage teams or members, read roles, permissions or permission policies, or list a gateway server's tools. Use a personal key for those.

Every change the agent makes is recorded in the Audit log under the key, so you can see what it did and roll it back.

Example: Refund approvals

We'll ask our coding agent to set up refund approvals for the support assistant. It lists our agents and finds support, lists our teams and finds Payments, and creates an escalation path that pages Payments and then our finance lead after 15 minutes. It then creates a Support pipeline that approves refunds up to $20 and sends the rest to Payments review, and saves the entry pipeline with a block that denies refunds over $500 and a Delegate block that hands the support assistant's requests to the Support pipeline. Before we trust it, we ask it to test a $75 refund: the preview reports that the request would go to a person through the Payments review path.

Checking it works

Ask the agent to list your pipelines and escalation paths, or open Approval pipelines and Escalation paths in the app: the revisions it saved appear with the key's name as the author. If a tool call is refused, the agent sees the same reason the app would show, such as a path that is still in use or a permission the key does not hold.