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.

Use call_public_api to inspect your calendar connections, including Microsoft primary-calendar health and visible meetings. The same permissions and privacy apply as in REST. Microsoft availability-only sync keeps times and discards any meeting details Microsoft sends. Connect, disconnect and consent changes require the browser and are unavailable through generated credentials.

For personal task lists, use call_public_api with GET /tasks/my; draft projects are excluded. Planning tools retain draft assignments and tentative capacity so agents can review work before activation. See Reading Data for the schedule state fields.

File writes record the connected user as the author. Named file tools return structured application errors, including retained-history capacity limits. See file tool errors and the Assets API.

Use link_asset to make a file available on a project. It reuses files already visible there, including images from the project’s conversation. Use save_asset_to_collection for a specific collection destination. Copies retain their AI creator attribution. See files and folders.

The update_staff_profile tool saves basic and portfolio changes together. If the save fails, both stay unchanged. To edit someone else, you must be an active admin or owner in the connection’s organisation, and the person must belong to it. Work-history requests through call_public_api use the same organisation boundary. See profile fields and permissions.

Use call_public_api for master-project operations. The connection can only access master projects in its own organisation, even if you belong to other organisations. Changes record the connected user as the author, and a save and its budget valuation succeed or fail together.

Use call_public_api to manage a project’s team. Membership changes use the connected user’s current authority, preserve explicit zero-hour allocations and keep financial response fields restricted.

Use call_public_api for saved project views. Personal views remain private, and shared views require the same project management rights as in the app. A failed default change leaves the previous default and saved layout unchanged.

Task and milestone changes also record the connected user as the author. Named tools and call_public_api stay within the connection’s organisation, even if you own another organisation. See the Tasks API and Projects API for field permissions and validation.

Connecting an agent

Connect agents from the web app:

Settings → Agent Connectivity

For OAuth clients, follow Agent Connectivity to sign in, approve the organisation and manage connected apps.

For manual connections, 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

OAuth clients

Add the tenant’s HTTPS /mcp URL to your client. Runnit returns a 401 challenge with a WWW-Authenticate resource metadata URL when credentials are missing or invalid. Discovery is available at /.well-known/oauth-protected-resource/mcp, /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server.

Runnit supports public clients using dynamic registration and authorization code with PKCE S256:

Endpoint	Required fields
POST /oauth/register	JSON client_name, redirect_uris; authentication method is none.
GET /oauth/authorize	client_id, exact registered redirect_uri, response_type=code, code_challenge, code_challenge_method=S256, resource; optional state and scope.
POST /oauth/token	Form-encoded grant_type=authorization_code, client_id, code, code_verifier, redirect_uri, resource.
POST /oauth/token	For refresh: grant_type=refresh_token, client_id, refresh_token, resource.
POST /oauth/revoke	Form-encoded client_id, token. Either token type revokes the whole connection.

The resource must exactly match the tenant’s HTTPS MCP URL. Redirects must use HTTPS or HTTP loopback, without fragments or embedded credentials. Registration accepts up to ten redirects. Client ID Metadata Documents and confidential client authentication are not supported. Register again if an unused client registration older than seven days is no longer recognised.

The scope is runnit:mcp, which permits reads and writes within the user’s live permissions. It is the default when scope is omitted. Other scopes are refused. Codes expire after five minutes, access tokens after one hour, and connections after 90 days. Refreshing rotates the refresh token without extending the connection’s expiry. Save the replacement token before refreshing again. Reusing a consumed code or rotated refresh token revokes the connection and returns invalid_grant.

Send the access token in Authorization: Bearer ... on every MCP request, including requests with a session ID. Token rotation can continue the same MCP session; another connection’s token cannot. Omit the apiKey tool argument. OAuth access tokens can use the same call_public_api tools as manual MCP tokens, but cannot authenticate direct /api/v1 requests. Consent and credential management require browser sign-in and are outside the public API and MCP.

Manual credentials

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 Settings → 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 the server URL to /mcp?auth=apiKey so protocol discovery can run before a tool supplies its credential. This option grants no access to data without a valid token.

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 Settings → 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, kanban boards and workflow stages, and time (log_time, submit_timesheet), with finance reads (get_uninvoiced_work, get_period_checklist, list_invoices, get_invoice, get_receivables, get_client_billing_profile) and one finance draft tool (draft_invoice) for organisations with Finance turned on. 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. Called without confirm, it reports the work the member still holds, and a member who holds work can only be archived with a handover (everything to one person, or tasks unassigned). reassign_member_work moves open tasks in bulk without archiving anyone, for a handover split across several people. The archive result reports the previous and resulting membership status, whether an invitation remains, userAccountDeleted: false, the handover applied, and a plain-language effect so an agent can state the outcome precisely.

The named invite_staff tool returns emailSent only; the invitation link is delivered by email and is never part of the result. 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.

The role tools (invite_staff, update_staff_role, archive_staff, update_user_role) follow the same rules as the app and REST API: you can only invite at or below your own role, only an owner assigns, changes or removes an owner, an admin manages roles up to admin, nobody changes their own role or removes themselves, and the last active owner can’t be demoted or removed. A refused call returns the reason as the tool error so the agent can explain it.

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 Settings → 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.

Finance workflow tools

Use get_finance_guide for the Finance User Guide and API reference supplied with the current release. Omit page for the index; then pass a page id and follow nextOffset until the page is complete. get_finance_operations lists areas, operation ids, path parameters and validated fields. Pass area for an operation list, or operation for its contract.

read_finance_operation accepts reviewed GET operations. perform_finance_action accepts reviewed mutations with confirm:true after the user authorises the specific effect. Both accept operation, optional parameters and query; actions also accept a JSON body or multipart. Responses preserve HTTP status and the route’s data or error. A confirmation preview reports confirmationRequired:true and changes nothing.

For example, after reading and reviewing an invoice:

{
  "operation": "POST /finance/invoices/:id/issue",
  "parameters": { "id": "<invoice-id>" },
  "body": {},
  "confirm": true
}

These tools use your live route permissions, financial visibility and approval rules. They are available to interactive workspace chat and unscoped generated credentials. Component, automation and explicitly scoped sessions keep their narrower tools. Bank details/payment files, signatures, statutory attestations, provider connections and deferred provider execution have explicit exclusions in the catalogue. call_public_api retains its existing external-client contract. See Finance with Ru for user guidance.

Finance returns entered budget prices separately from net sold and hourly rates. Source-based invoice drafts use prices before tax; incompatible inclusive requests are refused consistently through REST and MCP. See the Finance API for pricing fields and validation codes.

Finance forecast filters use the attributed share of mixed invoices, bills and expenses. See Forecast source filters for exclusions and weekly-total calculations.

Finance metric definitions come from the same catalogue used by the API. standard_billable_value supplies the denominator for realisation. Existing time approval and review routes share their recorded-value behaviour through call_public_api; see the Finance API reference.

Purchase totals use that same shared contract: approved billable purchases join budget used, split values reconcile, and later bill voids preserve earlier report months. See purchase totals.

Finance cost reports include received but unbilled purchases and dated self-billing relief. Generated REST and MCP credentials receive the same recorded values and source-reservation guards. See Finance API.

Bank settlement and reimbursement corrections preserve dated history through the same permissions and validation in REST and MCP. See the Finance API reference.

Period checklist supporting records are available through call_public_api with the same source permissions and pagination as REST. See the Finance API reference.

Self-billing supplier settings, signed agreement file retention and download, PDF delivery requests and their history are available through call_public_api. The same cost access, live permissions, organisation binding and request replay checks apply as on the public REST API.

Client participation

Client portal statement downloads, retainer views and quote or change acceptance require the signed-in client’s participation permissions. They are not exposed through generated-token REST or MCP. Agency-side Finance operations retain their existing token permissions. See Client Portal Billing.

Internal charge setup, providing credits and corrections use the shared Finance contract. See Internal chargebacks.

Finance reports and scenarios

Finance tools use the same recorded values and permissions as the app. Report money cells can include original amounts separately for each currency. Forecast and WIP totals include only the subjects the connected user may read.

Use model_scenario to draft alternatives with sections and pricing terms. Missing estimates remain explicit. Promoting an alternative needs a separate authorised action and keeps the usual approval process. The Finance API reference describes source-detail, BAS and scenario fields available through call_public_api too.

Billing-entity logo changes also use the public API path. Upload an eligible organisation asset, then save its ID on the entity. The same settings access and image checks apply to both REST and MCP.

For file-saving tools, repeated saves reuse the existing saved asset for the same source and destination folder and name. See Files and folders for details.

Private file reads

An ordinary user-generated credential can read a known private file through read_file or read_document when you are its uploader, own a linked conversation, or are an owner or admin of the authorising organisation. You also need permission to view assets; Finance documents keep their Finance permissions. Reading the file does not grant conversation access.

Private files remain out of listings and search. Internal sessions limited to a job, client or tool set continue to reject private-file reads. See file tools and private-file access.

Workspace maintenance

Your existing connection keeps working during destination preparation. A failure before maintenance starts does not require a new key or an MCP reconnection.

Keep using your workspace hostname through the move. Cached DNS continues to work; you do not need to change the server address or clear your DNS cache.

During maintenance for a workspace move, MCP, its OAuth endpoints and the REST API return HTTP 503 with Retry-After: 30. Wait before reconnecting. The maintenance response is returned before a tool runs, including call_public_api. Browser visitors see a maintenance page at the same workspace address.

After the workspace reopens, sign in again and reconnect your MCP client. If you connect with an API key, generate a new key for that workspace and replace the saved credential. Tool permissions and organisation scope still follow the connected user. See maintenance and authentication.

A workspace move preserves your browser sign-in method, including Google or Microsoft. Sign in that way when reconnecting your AI client. If a provider return fails, start a fresh sign-in from the workspace login page. See signing in after a move.

Invoice template previews and delivery use the same Finance routes through call_public_api. This includes unsaved sample previews, template/style edits, PDF downloads and email queue status. POST and PATCH calls require the tool’s normal confirmation, including the preview POST that does not save changes. See invoice API details.