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, project history. See Reading Data.
• Write tools: create and update projects, tasks, milestones, briefs, 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.
• Complete REST API coverage: call_public_api for documented /api/v1 operations that do not have a dedicated MCP tool.

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.

Complete REST API coverage

Use call_public_api when you need a documented public API operation that has no dedicated MCP tool. This includes operations such as board and workflow stage management, report exports, closure dates, master project changes, saved views, permission administration, asset folders, tags and versions, and user imports.

Prefer a named MCP tool when one exists. Named tools have smaller schemas and responses designed for AI clients. call_public_api is the complete-coverage fallback and follows the relevant REST API reference.

Argument	Use
method	GET, POST, PUT, PATCH, or DELETE. It defaults to GET.
path	The path after /api/v1, beginning with one slash. For example, /organizations/<organisation-id>/boards.
query	Optional query values. Arrays create repeated query parameters.
body	Optional JSON request body. Do not use it with multipart.
multipart	Optional form fields and base64-encoded files for upload endpoints. Do not use it with body.
accept	Optional response media type.
confirm	Required as true for every non-GET request.

For example, list an organisation’s boards:

{
  "method": "GET",
  "path": "/organizations/<organisation-id>/boards"
}

To change data, review the matching API reference first and confirm the call:

{
  "method": "PATCH",
  "path": "/projects/<project-id>",
  "body": {
    "name": "Updated project name"
  },
  "confirm": true
}

The result includes the HTTP status and response body. JSON is returned in data, text and CSV in text, and other binary content in bodyBase64 with encoding: "base64". Request and response bodies are limited to 25 MiB, and the request times out after 60 seconds. Redirects are returned without being followed.

The public API still applies the connected user’s current permissions, organisation binding, client assignments, resource grants, validation, rate limit, and audit attribution. An MCP session token cannot authenticate the REST API directly. The tool performs the authorised bridge call on its behalf.

Note

call_public_api accepts tokens generated from Agent Connectivity and per-user rnk_ API keys. It is unavailable to restricted internal sessions, such as sessions limited to a client, job, automation, or specific tool list. Those sessions keep their named-tool limits.

Image and video generation

Omit the model argument from generate_image, edit_image, generate_video, and generate_video_from_image unless you have a specific supported model ID. Runnit selects the configured model for that capability and normalises supported friendly names.

Generation follows the active organisation’s AI billing mode. A credit organisation needs enough balance for the estimated request. An own-key organisation needs its fal.ai credential under Admin → AI API Keys and never falls back to a platform key. See AI Credits for the organisation workflow.

Files and folders

Collections can organise files into folders. File tools address folders with a folderPath argument: a slug path such as /campaign-assets/q3. Display names also work ("Campaign Assets/Q3" is normalised to the same path), and paths are matched case-insensitively.

• list_files returns folders (the file’s folder paths) and primaryFolder for every file (folders is empty for files at the collection root), and accepts an optional folderPath argument to list only that folder.
• read_file accepts an optional folderPath to pick the right file when the same name exists in more than one folder. Without it, the most recently updated match anywhere in the collection is returned; the response includes folders and primaryFolder so you can see which one you got.
• create_or_update_file accepts an optional folderPath to file the document into a folder, creating missing folders automatically. With a folderPath, only a same-named file in that folder is updated; same-named files elsewhere in the collection are left alone.
• save_asset_to_collection accepts an optional folderPath to file the copy into a folder of the target collection.

Results only include files the connected user can read: private files never appear in listings.

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. Optional workflowStage (stage id or name, draft-category only) chooses the entry stage, for example a pipeline’s Enquiry. A successful result contains a read-after-write verified project and canonical projectUrl. Use projectUrl verbatim in user-facing links. If verification fails, do not invent a URL and retry only when retryable is true.	Project creation
update_project	Update a project’s fields. Cannot set the status to archived (archiving happens in the app), and archived projects reject writes.	Project update
delete_project	Delete a project and everything in it. Destructive.	Project deletion
create_milestone / update_milestone / delete_milestone	Manage project milestones. update_milestone also takes an achieved flag: true marks the milestone achieved and stops its due and overdue notifications, false reopens it. You do not need to do this before closing a project, because moving a project to done or completed closes out its open milestones for you. delete_milestone is destructive.	Project update

Tasks

Tool	Purpose	Required access
create_task	Create a task in a project. Only name is required; assignment, estimate, and planned start are optional. A schedule is built only when plannedStartDate is supplied. Dependencies are validated before the task is saved. A dependency or schedule failure does not retain the new task, so the call can be retried without creating a duplicate.	Task creation; task assignment when choosing an assignee; task-wide update plus schedule management when adding dependencies
update_task	Update task fields. A start creates or rebuilds the schedule and moves a pending backlog task to scheduled. An estimate change on a task with a day-by-day breakdown keeps the planned window and rescales the daily hours when the new total fits it; otherwise the schedule rebuilds from the start. An estimate-only or assignment-only change keeps an undated task unscheduled; reassignment moves any existing schedule ownership. The result includes task and its pre-change previousTask snapshot for follow-up edits or reversals.	Assigned-task or task-wide update for general fields; task assignment for reassignment; task-wide update plus schedule management for dates and estimates
update_task_status	Change status and optional whole-number progress using the same start, completion, reset, cancellation, and reopen rules as the app. Completion can include actual hours and notes. The result includes task and its pre-change previousTask snapshot.	Assigned-task update, project ownership, or task-wide update access
delete_task	Delete a task. Destructive.	Task deletion or project owner/admin override
create_task_comment	Add a comment to a task. Comments post into the task’s chat thread, so they notify the assignee, project owner, and other participants, and can be replied to in the app.	Task comments
involve_user	Pull a person into a task or project: posts a message into its chat thread with an @mention of them, so they are notified with a link and can reply there. Provide exactly one of taskId or projectId. Fails if the person cannot already see the work.	Task comments (tasks) or project view (projects); the mentioned person needs access to the project
post_project_note	Post a note into a project’s chat thread authored as Ru rather than as the acting user. Meant for a durable record of assumptions, decisions, and trade-offs made while working on the user’s behalf. Fails on archived projects.	Project view; the acting user must be able to post in the project’s chat
set_task_table_values	Set custom table-column values on a task. Values are validated against the project’s effective columns; use list_table_columns first for keys, types, and dropdown option keys.	Project owner, project admin, or organisation manager
create_table_column	Create a custom table column on a project, or at client/organisation scope so it appears on every matching project. Supports all eight column types and the optional settings.ai block that makes it an AI-filled column.	Project owner, project admin, or organisation manager; shared scopes also need the shared table columns permission
fill_table_column	Run the AI fill for a column with an enabled ai block. Targets specific taskIds, only empty cells (onlyEmpty), only cells whose task inputs and instruction changed (onlyStale), or every task (max 100). Values are validated like manual input and stamped with per-cell provenance.	Project owner, project admin, or organisation manager
set_task_allocations	Replace a task’s day-by-day hour breakdown (manual schedule mode). Sets the planned window to the allocation dates and rebuilds schedule segments. Prefer create_task or update_task with estimatedHours for automatic scheduling.	Task-wide update plus schedule management, or project owner/admin override
set_task_dependencies	Replace a task’s finish-to-start dependency list (same project, max 25, cycles rejected). The task and its transitive dependents are forward-shifted through the scheduler; returns the cascade summary. create_task also accepts dependsOn directly.	Task-wide update plus schedule management, or project owner/admin override

plannedEndDate is calculated from planned start and estimated hours. Do not send it to update_task.

When a scheduled create_task call omits estimatedHours, Runnit uses one day from the organisation’s Daily capacity setting, with 8 hours as the fallback. Name-only tasks return an empty scheduleSegments array.

Schedule

Tool	Purpose	Required access
block_out_dates	Mark a date range (inclusive, up to 366 days) as unavailable for a user, with an optional type (leave, appointment, other) and reason. Optional hoursUnavailable (greater than 0, less than 24) makes the block partial: that many hours per day are unavailable and the scheduler books at most the remaining capacity; omit it for whole days. Partial blocks on the same day stack, and hours at or above the organisation’s daily capacity block the whole day. To express “hours available”, subtract from the daily capacity first. When conflicting work is booked on the dates, resolution decides the outcome: flag (the default) leaves the bookings in place and raises conflict warnings; replan refits work to the remaining hours and moves the excess to the next available working days, cascading dependants. The response includes the conflict or replan report; surface it to the user, and never choose replan without their explicit confirmation.	Own dates: any member. Another user’s dates: schedule management
update_blocked_dates	Change an existing blocked-dates entry by blockId: move or resize the range, change the type or reason, or adjust hoursUnavailable (a number sets partial hours, null converts the entry to whole days, omitting leaves it unchanged). Only days the change makes stricter (newly covered, newly whole-day, or increased partial hours) re-run the conflict flow with the same resolution choice; loosening or shrinking never moves scheduled work. Never choose replan without the user’s explicit confirmation.	Own entries: any member. Another user’s entries: schedule management
remove_blocked_dates	Delete a blocked-dates entry by blockId, freeing that capacity. Removing a block never pulls already-scheduled work earlier; replan tasks explicitly if the freed days should be used.	Own entries: any member. Another user’s entries: schedule management

The matching read tool is get_blocked_dates. See Reading Data.

Briefs

Tool	Purpose	Required access
update_brief_draft	Replace the draft markdown of a Brief Builder session. The new draft appears in the owner’s open Brief Builder tab.	Brief editing; session owner or organisation admin

Boards and workflow stages

Tool	Purpose	Required access
list_boards	List visible kanban boards with their columns and stage mappings.	Organisation membership
list_workflow_stages	List the organisation’s workflow stages and categories.	Organisation membership
create_board	Create a board from named columns; missing stages are created with a category in the same step. Optional members (ids or emails) and memberGroups (group ids, slugs, or exact names) limit the board to those people and groups. Optional taskTableColumns sets the default task-table columns for projects on the board. Optional recordFormId sets the board’s details form, and records ({"newCardWorkspaceMode": "lean"}) makes projects created through the board open as lean records.	Kanban management
update_board	Rename a board, change its client scope, replace its columns, replace its audience (members and memberGroups form one audience; [] for both reopens it to everyone), set taskTableColumns (the default task-table columns for projects on the board; null reverts to the organisation default, and the default board always follows the organisation setting), set recordFormId, or set records ({"newCardWorkspaceMode": "lean"} for lean records; null reverts to full projects).	Kanban management
list_user_groups	List the organisation’s user groups with member counts, for resolving memberGroups references.	Organisation membership
manage_workflow_stages	Add, rename, or delete workflow stages. Deletions are destructive and require confirmation with a reassignment stage.	Kanban management
delete_board	Delete a board (a view; projects and stages are untouched). Destructive; requires confirmation.	Kanban management

Board and stage writes are not available to client-scoped sessions, and list_boards shows a client-scoped session only the default board plus that client’s boards.

Staff

Tool	Purpose	Required access
invite_staff	Invite a person to the organisation. Returns the invitation token, URL, and emailSent. Non-production datasets create the invitation without sending email.	Member management
update_staff_role	Change a member’s organisation role. Requires confirmation.	Role management
archive_staff	Archive an organisation membership. It does not delete the user account or revoke a pending invitation. The result reports the exact membership effect. 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

An invitation remains valid when invite_staff returns emailSent: false. Use its returned invitation URL if the user wants to share the link manually.

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

Note

AI Directives collections are protected. Creating, updating, or deleting files in an AI Directives collection, or changing the collection itself, additionally requires the connected user to hold the “Manage AI agents” permission. See AI Directives.

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.

For archive_staff, a successful confirmation reports the previous and resulting membership status, whether a pending invitation remains, userAccountDeleted: false, and a plain-language effect. Use those fields literally. Archiving a membership is not deletion of the user account.

Caution

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