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)
- In Claude: Settings → Connectors → Add custom connector.
- Name: Ratio. URL:
https://ratioteams.com/api/mcp. - 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:
- In ChatGPT: Settings → Connectors → Advanced and turn on developer mode.
- Create a connector with the URL
https://ratioteams.com/api/mcpand OAuth authentication. - Approve access in Ratio.
- 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.
- OAuth 2.1 (recommended). Ratio is its own authorization server, with dynamic client registration and PKCE S256. A request without credentials gets a
401withWWW-Authenticateandresource_metadata, and the client starts the sign-in on its own. The access token lasts one hour and is renewed with a 30-day refresh token. OAuth tokens work only for the MCP server. - Personal API key (
tasks_fk_…). The same one the REST API uses.
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.
| Tool | What it does | Parameters | Kind |
|---|---|---|---|
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 asked | Tool | Tokens (approx.) |
|---|---|---|
| Find out who is connected | whoami | 30 |
| See the projects | list_projects | 100 |
| See a project | get_project | 80 |
| Create a task | create_task | 120 |
| Change a task's status | set_task_status | 260 |
| Comment on a task | add_comment | 20 |
| Read a task with 5 comments | get_task | 650 |
| Search by text | search | 900 |
| List a project's tasks | list_tasks | 40 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
- The assistant acts as the person who connected it: it sees only their spaces and projects, and their role in each space (reader, member or owner) decides what it can do. Anything from another space answers as if it didn't exist.
- Everything it does stays in each task's history under that person's name, marked "via API".
- The role is checked on every request: if the person is made a reader or removed from the space, the assistant loses access at once.
- Connections are listed and cut off from Credentials, in the portal. Disconnecting removes access immediately.
- A request with an
Originfrom another site is rejected with403. - The limit is 30 requests per second per credential, with bursts of up to 60. Past it,
429withRetry-After.
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"}'