MCP Tools

All internal file and asset interactions must use MCP tools: do not use HTTP endpoints for Runnit files or assets.

Authentication modes

Two user-scoped credential types work with every tool: short-lived MCP session tokens (mcps_...) from Agent Connectivity, and long-lived per-user API keys (rnk_...) from Admin → API Keys. See API Keys & Authentication.

Runnit supports two ways to present the credential:

1. External MCP clients (Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code Copilot Agent mode, generic streamable HTTP clients) send it once as an Authorization: Bearer ... header. In this mode, tool calls omit apiKey.
2. Payload-based workflows that cannot set per-server MCP headers. In this mode, every tool call must include the apiKey argument taken from the workflow input payload.

Caution

For payload-based workflows, MCP tool calls fail without the apiKey argument. Use the field name apiKey (not the deprecated organizationApiKey), and pass the actual token value: never the literal string {{apiKey}}.

The credential is an opaque string prefixed with mcps_ (session token) or rnk_ (API key). Treat it as a secret: do not parse or split it. It reflects the owning user’s permissions, resolved live on every call. Session tokens are short-lived, so payload-based workflows should always read the current apiKey from this run’s input rather than reusing a previous token.

Example: extracting and using apiKey

Given this input:

{
  "apiKey": "mcps_9f2c8a1b...",
  "jobCollectionId": "91c52864-fd2b-4732-9f53-fd6d28606482"
}

A payload-based tool call must include the actual token value:

{
  "tool": "read_file",
  "arguments": {
    "apiKey": "mcps_9f2c8a1b...",
    "collectionId": "3e7c3220-7f08-4754-8f8c-d93ca946eb3d",
    "fileName": "brand_guidelines.md"
  }
}

Results reflect user permissions

A read may legitimately return fewer items, or an empty/forbidden result, if the connected user lacks permission. That is expected behaviour, not an error to retry.

Tool groups

• Project management (read): projects, tasks, comments, schedules, milestones, costs, clients, users, jobs, briefs, agents, project history. See Reading Data.
• Write tools: create and update projects, tasks, milestones, staff, clients, rate cards, and collections. See the write tools section below.
• Files & assets: create, update, read, list, link, unlink, search, delete.
• DAM discovery: search_assets (hybrid semantic + structured search) and find_similar_clients (brand/tone-of-voice similarity).
• Generation: image and video generation/editing.
• Web: scrape_url, crawl_website.

User-authored components run in a sandbox and may call only a read-only subset of tools; they cannot use write, generation, scraping, build, or conversation tools.

Write tools

The server exposes write tools that create and change Runnit data. Every write tool enforces the connected user’s live permissions, so a call fails when the user lacks the required access in the app.

Projects and milestones

Tool	Purpose	Required access
create_project	Create a project.	Project creation
update_project	Update a project’s fields.	Project update
delete_project	Delete a project and everything in it. Destructive.	Project deletion
create_milestone / update_milestone / delete_milestone	Manage project milestones. delete_milestone is destructive.	Project update

Tasks

Tool	Purpose	Required access
create_task	Create a task in a project.	Task creation
update_task	Update a task’s fields.	Task assignment
update_task_status	Change a task’s status.	Task assignment
delete_task	Delete a task. Destructive.	Task assignment
create_task_comment	Add a comment to a task.	Task comments

Staff

Tool	Purpose	Required access
invite_staff	Invite a person to the organisation.	Member management
update_staff_role	Change a member’s organisation role. Requires confirmation.	Role management
archive_staff	Deactivate a member. Destructive.	Role management
update_staff_profile	Update a member’s profile.	Member management
add_staff_history_entry / update_staff_history_entry / delete_staff_history_entry	Manage a member’s work-history entries.	Member management

Clients

Tool	Purpose	Required access
create_client / update_client	Create or update a client relationship.	Client management
remove_client	Remove a client relationship. Destructive.	Client management

Rate cards

Tool	Purpose	Required access
list_rate_card_roles / list_client_rate_cards	Read rate-card data.	Financial reporting
create_rate_card_role / update_rate_card_role / archive_rate_card_role	Manage rate-card roles.	Organisation settings management
create_client_rate_card / update_client_rate_card	Manage client rate cards.	Organisation settings management

Collections

Tool	Purpose	Required access
create_collection / update_collection	Create or update an asset collection.	Asset upload
delete_collection	Delete an asset collection. Destructive.	Asset upload

Destructive tools require confirmation

delete_project, delete_task, delete_milestone, archive_staff, remove_client, delete_collection, and update_staff_role require a confirm: true argument. Called without it, the tool does not act: it returns a preview describing what would happen so the agent can check with the user first, then call again with confirm: true.

Caution

delete_project removes the project and all of its tasks, schedules, and assets. There is no undo. Always review the preview before confirming.