Ratio Docs

Ratio MCP server

Ratio has an official, remote MCP (Model Context Protocol) server. Through it, an AI assistant sees the projects of the person who connected it and works on them —looks up, creates and updates tasks, comments, runs sprints— with that person's permissions.

Address
https://ratioteams.com/api/mcp
Transport
Streamable HTTP, JSON-RPC 2.0. JSON responses, no session.
Authentication
OAuth 2.1 with PKCE and dynamic client registration, or a personal API key.
Tools
38, read and write. See the list.
Protocol
Versions 2025-06-18, 2025-03-26 and 2024-11-05.
Price
Included in every plan, the free one too.
Tokens
About 8,200 when you connect it. See the detail.

Connecting a client

Claude (web, desktop and mobile)

  1. In Claude: Settings → Connectors → Add custom connector.
  2. Name: Ratio. URL: https://ratioteams.com/api/mcp.
  3. Connecting opens Ratio to sign in and approve access. No key needed.

Claude Code

claude mcp add --scope user --transport http ratio https://ratioteams.com/api/mcp

Then, inside Claude Code: /mcp → ratio → Authenticate. The browser opens to approve access in Ratio.

Codex

codex mcp add ratio --url https://ratioteams.com/api/mcp

Then: codex mcp login ratio. The browser opens to approve access in Ratio. Ratio is also in ChatGPT's plugin store: it can be installed from there.

ChatGPT

Ratio is in ChatGPT's plugin store: install it from there. To connect it by hand:

  1. In ChatGPT: Settings → Connectors → Advanced and turn on developer mode.
  2. Create a connector with the URL https://ratioteams.com/api/mcp and OAuth authentication.
  3. Approve access in Ratio.
  4. Open a new chat and pick the Ratio connector in that chat: a chat that was already open doesn't see the tools.

What ChatGPT can do depends on its mode, not on Ratio. With developer mode on it uses every tool, including the ones that create and move tasks. Without it, it only uses search and fetch: it can search and read tasks, but not change them. If the connector shows as connected and ChatGPT says it has no tools, it is almost always that developer mode is off for that account, or that the chat is older than the connection.

Cursor

In Settings → MCP → Add server, or in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ratio": { "url": "https://ratioteams.com/api/mcp" }
  }
}

Other clients

Any client that supports remote MCP servers over HTTP works. If the client doesn't handle OAuth, a personal API key can go in the header:

{
  "mcpServers": {
    "ratio": {
      "type": "http",
      "url": "https://ratioteams.com/api/mcp",
      "headers": { "Authorization": "Bearer ${RATIO_API_KEY}" }
    }
  }
}

Keys are created in the portal, under Credentials. They start with tasks_fk_ and are shown only once.

Authentication

The server accepts two credentials, always in Authorization: Bearer …. It never accepts the browser cookie: what connects through MCP is an agent, not a person at the screen.

The metadata is at https://ratioteams.com/.well-known/oauth-protected-resource and https://ratioteams.com/.well-known/oauth-authorization-server.

Tools

Each tool calls the same function as the REST API, with the same permissions. Read tools carry readOnlyHint; the ones that change or delete something carry destructiveHint, so the client asks for confirmation before using them.

ToolWhat it doesParametersKind
search Searches tasks by text across every project the person can see (what ChatGPT connectors use). query (optional) read
fetch One whole task by the id that search returns, as text (what ChatGPT connectors use). id read
whoami The connected Ratio account: id, name and email. — read
list_spaces The person's spaces, with their role in each one. — read
list_people The people they share a space with; with space_id, that space's members and roles. space_id (optional) read
list_projects The projects the person can see, with their space and role. space_id (optional) read
get_project One project, with its icon and links, and whether they can write tasks or manage it. project_id read
update_project Edits a project's name, description or status; only what is sent changes. project_id name (optional) description (optional) status (optional) changes or deletes
set_project_icon Sets a project's icon: a key from the catalog, or its own picture as base64. project_id icon (optional) image_base64 (optional) changes or deletes
list_project_links A project's links (production, repository, docs…). project_id read
add_project_link Adds a link to a project (up to 20). project_id url label (optional) kind (optional) write
update_project_link Edits a project link; only the fields sent are changed. project_id link_id url (optional) label (optional) kind (optional) changes or deletes
delete_project_link Removes a project link. project_id link_id changes or deletes
list_task_types The task types a project accepts. project_id read
list_modules A project's modules. project_id read
list_sprints A project's sprints. project_id read
create_sprint Creates a sprint, optionally bringing the open backlog tasks. project_id name (optional) starts_on (optional) ends_on (optional) traer_backlog (optional) write
close_sprint Closes a sprint and sends what is still open to another sprint, the backlog or done. sprint_id destino (optional) changes or deletes
list_tasks A project's tasks, filtered by status, sprint or assignee. Each comes without its description (`has_description` says if it has one): read it with `get_task`. `include_description` brings it too. project_id status (optional) sprint_id (optional) assignee (optional) agent_assignee (optional) include_description (optional) read
get_task One task, whole: the latest comments (older ones through `list_comments`), checklist, files, dependencies and diagrams. task_id comments_limit (optional) include_logs (optional) comments_before (optional) read
list_comments A task's comments, a page at a time: the latest ones, `before_id` goes back; kind all, comment or log. task_id limit (optional) before_id (optional) kind (optional) read
rate_ratio Records the person's own rating of Ratio, 1 to 5 stars and an optional comment. stars (optional) comment (optional) declined (optional) write
list_docs A project's documentation pages, in order, without their body. project_id read
get_doc One documentation page, whole, in Markdown. doc_id read
create_doc Creates a documentation page in a project. project_id title body (optional) write
update_doc Edits a documentation page; the previous version stays in its history. doc_id title (optional) body (optional) changes or deletes
get_task_file One of a task's attachments, to look at it: an image comes back as an image, a text as text. task_id file_id read
create_task Creates a task in a project. project_id name description (optional) tipo (optional) module_id (optional) sprint_id (optional) due_date (optional) color (optional) assignee_ids (optional) agent_assignee (optional) write
update_task Edits a task; only the fields sent are changed. task_id name (optional) description (optional) tipo (optional) module_id (optional) sprint_id (optional) due_date (optional) color (optional) assignee_ids (optional) agent_assignee (optional) changes or deletes
set_task_status Changes a task's status (blocking requires a reason). task_id status block_reason (optional) block_kind (optional) changes or deletes
delete_task Deletes a task (only whoever manages the project). task_id changes or deletes
add_comment Comments on a task; kind=log for an agent's progress notes. task_id text kind (optional) write
update_comment Edits one of the person's own comments. comment_id text changes or deletes
delete_comment Deletes a comment. comment_id changes or deletes
add_checklist_item Adds an item to a task's checklist. task_id text write
update_checklist_item Checks, unchecks or renames a checklist item. check_id done (optional) text (optional) changes or deletes
add_dependency Makes a task wait for another one of the same project. task_id depends_on write
remove_dependency Removes a dependency between two tasks. task_id depends_on changes or deletes

How much it costs to connect it

Ratio doesn't use any AI model of its own: it only answers what the AI you connected asks for. The tokens are spent by that AI, within each person's plan (Claude's, ChatGPT's…), and Ratio charges nothing for it: the MCP server is included in every plan. This is what Ratio adds to a conversation. They are estimates, at 1 token per 3.5 characters, based on what the server really returns.

When you connect it

So the AI knows what it can do, the client loads the list of Ratio's 38 tools: about 8,200 tokens per conversation. Some clients load it only when it's needed. This number is computed from the real list: if a tool changes, it changes here.

Every time it's used

What it is askedToolTokens (approx.)
Find out who is connectedwhoami30
See the projectslist_projects100
See a projectget_project80
Create a taskcreate_task120
Change a task's statusset_task_status260
Comment on a taskadd_comment20
Read a task with 5 commentsget_task650
Search by textsearch900
List a project's taskslist_tasks40 per task (10 tasks: 340; 40 tasks: 1,700)

Measured with tasks whose description is 450 characters long: a longer description weighs more. list_tasks returns each task without its description (read it with get_task), so listing a big project costs little; with include_description it brings it too and each task adds about 260 tokens. Asking by status or by sprint ("the in-progress tasks of the current sprint") instead of "all the tasks" costs even less.

Permissions and security

Errors

An operation error —missing permission, something that doesn't exist, a malformed value— comes back as the tool's result with isError: true and the reason in text, so the assistant can read it and fix it. Protocol errors follow JSON-RPC: -32601 for an unknown method and -32700 for broken JSON.

Example

Listing the tools with an API key:

curl -s https://ratioteams.com/api/mcp \
  -H "Authorization: Bearer $RATIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'