MCP server

https://api.median.sh/mcp

The server has two tools. median_run runs TypeScript against a typed median client, so one call can filter, join, loop and batch. median_docs returns that client's TypeScript declarations. Admins and owners also find the URL in Settings → API under MCP.

Connect a client

Claude Code

claude mcp add --transport http median https://api.median.sh/mcp

Run /mcp in Claude Code, pick median and sign in. Add --scope user to use it in every project.

Claude Desktop

Add a custom connector in Claude under Customize → Connectors, with the server URL. Then click Connect and sign in. On Team and Enterprise plans an owner adds the connector first, in Organization settings → Connectors.

Cursor

{
  "mcpServers": {
    "median": { "url": "https://api.median.sh/mcp" }
  }
}

Use .cursor/mcp.json instead for one project. Cursor asks you to sign in when it connects.

VS Code

{
  "servers": {
    "median": { "type": "http", "url": "https://api.median.sh/mcp" }
  }
}

VS Code asks you to sign in when the server starts.

Codex

codex mcp add median --url https://api.median.sh/mcp
codex mcp login median

Or add it to ~/.codex/config.toml:

[mcp_servers.median]
url = "https://api.median.sh/mcp"

Windsurf

{
  "mcpServers": {
    "median": { "serverUrl": "https://api.median.sh/mcp" }
  }
}

Any other client that speaks streamable HTTP and OAuth works with the same URL. See Protocol.

Authorize

The client opens Median in a browser. Sign in, then click Allow on the page titled Connect and the client's name. The page names the organization the client gets and says it acts as you.

Scripts and CI

Send MEDIAN_KEY as a bearer token and skip the browser. A key acts as an admin of its organization. Inviting, changing roles and removing members refuse a key with needs_a_person.

curl https://api.median.sh/mcp \
  -H "Authorization: Bearer $MEDIAN_KEY" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

median.account.me, createOrg and useOrg are about a person, so they need an OAuth token and refuse a key with token_required.

Tools

Topics: billing, account, conversations, customers, knowledge, signals, tasks, feedback, tools, org, site, agent, integrations, webhooks, analytics, docs. An unknown topic returns an error that lists them.

A failed run comes back as a tool result with isError: true and the error message.

The median client

await freely, log with console.log, and return the value you want back. Types are stripped before the code runs, so they are not checked.

const waiting = await median.conversations.list({
  status: "open",
  needsHuman: true,
});
return waiting.map((c) => ({ id: c.threadId ?? c.id, subject: c.subject }));

Every method calls the same backend function as its management API route, so shapes and errors match that reference. Roles apply the same way. See roles.

The same methods run outside the sandbox too. median call <method> in the CLI and POST /v1/call/{method} take the same names and arguments, and return the same values. The Median assistant works through the same list, so anything it can do, a method here can do.

A median.sh link works in place of an id in the methods of median.conversations, median.customers, median.knowledge and median.signals, and as the signalId of median.tasks.adopt:

const link = "https://median.sh/signal/q5776nawkbmazaj4qv4p26y3v98d83qc";
const { signal } = await median.signals.get({ signalId: link });
return signal.title;

The conversationId arguments of median.tools and median.billing.logs take the bare id.

Sandbox limits

The code runs in an isolated JavaScript engine with no network, no filesystem and no timers. median calls are real reads and writes.

Anything shaped like a Median credential is replaced with [redacted] in error text.

Protocol

Sign in limits

POST /oauth/register and POST /oauth/device_authorization are limited per caller address and answer 429 with slow_down when over. See Rate limits.

Access and revocation

Troubleshooting