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.

Set up

1. Sign in to Runnit.
2. Open Admin → Agent Connectivity.
3. Choose the connection URL (your deployed HTTPS backend, e.g. https://api.runnit.io/mcp).
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.

It also exposes write tools for projects, tasks, staff, clients, rate cards, and asset collections. 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.

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.