MCP Server

Runnit exposes a streamable HTTP Model Context Protocol (MCP) endpoint so external AI agents can use Runnit tools with the same permissions as the connected user.

Connecting an agent

Connect agents from the web app:

Admin → Agent Connectivity

That page creates a user-scoped MCP token and shows setup commands for common agent clients. The token is tied to your Runnit account and organisation role, so permission changes apply to future tool calls without issuing organisation-wide API keys to the agent.

Endpoints

Endpoint	Purpose
POST /mcp	Streamable HTTP MCP endpoint used by agent clients.
GET /mcp/health	MCP server health check.
POST /api/me/mcp-agent-session	Mint a user-scoped MCP token for the signed-in user.
DELETE /api/me/mcp-agent-session	Revoke a user-scoped MCP token.

Use the Agent Connectivity page rather than calling the session endpoints directly, so the token is created with your browser session and current organisation context.

Authentication

The MCP server accepts two user-scoped credential types. Both resolve to the same user-bound principal, and permissions are resolved live on every call:

• MCP session tokens (mcps_...): short-lived tokens minted from the Agent Connectivity page. Best for interactive agent sessions.
• Per-user API keys (rnk_...): long-lived keys (up to 2 years) created from Admin → API Keys. The same key also authenticates the public REST API, so one credential can drive both surfaces. See API Keys & Authentication.

Either credential can be delivered in two ways:

1. Bearer header: configure the MCP server with Authorization: Bearer <mcps_token or rnk_key>. Use this for Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code Copilot Agent mode, and generic streamable HTTP clients. Tool calls omit the apiKey argument.
2. Per-tool apiKey: for payload-based workflows that cannot set MCP server headers. Pass the same mcps_ token or rnk_ key as the apiKey argument on every tool call.

A valid credential pauses if its owner has not accepted the current Terms of Service. The MCP request is refused before any tool runs. Sign in to Runnit in a browser as that user, review and accept the current version, then retry with the same credential.

Set up

1. Sign in to Runnit.
2. Open Admin → Agent Connectivity.
3. Check the connection URL. It defaults to the current Runnit environment with /mcp appended. Choose Local app only when your agent and the Runnit backend are running on the same computer.
4. Generate a connection token for the active organisation.
5. Copy the command for your AI tool and run it locally.
6. Verify the server is connected in your agent and request Runnit data.

Claude Code

claude mcp add-json runnit '{"type":"http","url":"https://api.runnit.io/mcp","headers":{"Authorization":"Bearer mcps_..."}}'
claude mcp get runnit

Generic MCP JSON

{
  "mcpServers": {
    "runnit": {
      "type": "http",
      "url": "https://api.runnit.io/mcp",
      "headers": { "Authorization": "Bearer mcps_..." }
    }
  }
}

Available tools

The server exposes tools across projects, tasks, comments, schedules, milestones, costs, clients, users, jobs, briefs, agents, and project history; files and collection assets; DAM discovery (search_assets, find_similar_clients); image and video generation; and web scraping.

For public API operations without a dedicated MCP tool, use call_public_api. It covers every documented /api/v1 operation while keeping the same user permissions, validation, and response behaviour as the REST API. See MCP Tools.

Runnit treats this parity as a release requirement. API and product updates must keep user-generated MCP connections in sync with the public REST surface.

It also exposes write tools for projects, tasks, staff, clients, rate cards, asset collections, and kanban boards and workflow stages. Each write tool enforces the connected user’s capabilities, and destructive tools require an explicit confirm: true argument before they act. See MCP Tools for the tool contract and the full write-tool list.

The named update_task and update_task_status tools return the resulting task plus previousTask, a snapshot captured before the change. Agents can use that context for a later edit or reversal without guessing the earlier status or progress. The update still uses the same validation, permissions, organisation binding, side effects, and failure behaviour as the matching REST operation.

The named archive_staff tool archives the organisation membership. It does not delete the user account or revoke a pending invitation. Its result reports the previous and resulting membership status, whether an invitation remains, userAccountDeleted: false, and a plain-language effect so an agent can state the outcome precisely.

The named invite_staff tool returns emailSent with the invitation token and URL. Demo, sandbox, and training datasets create the pending invitation without sending email, so emailSent is false. The matching REST route and call_public_api return the same delivery state.

Troubleshooting

Symptom	Fix
Agent connected but asks for an API key	Re-register from Agent Connectivity with a real token, then restart the client. Bearer-header clients should omit apiKey.
Placeholder token in config	Remove the entry and generate a real token; placeholders are rejected.
Production client cannot connect	Use the public HTTPS MCP URL and confirm /mcp/health is reachable.
Token expired	Generate a new token from Agent Connectivity and re-register, or switch to a longer-lived API key from Admin → API Keys.
Current Terms of Service not accepted	Sign in to Runnit as the user who created the credential, accept the current Terms in the browser, then retry with the same credential.
Token rejected after an account was deactivated	Tokens and API keys stop working as soon as the account that created them is deactivated, the same as signing in does. Ask an administrator to reactivate the account, or re-register with a token created by an active account.