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: 23, 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.

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.

ChatGPT

In ChatGPT: Settings → Connectors → Advanced and turn on developer mode.
Create a connector with the URL https://ratioteams.com/api/mcp and OAuth authentication.
Approve access in Ratio.

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 401 with WWW-Authenticate and resource_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 descriptions inside the server are in Spanish.

Tool	What it does	Parameters	Kind
`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, and whether they can write tasks or manage it.	`project_id`	read
`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.	`project_id` `status` (optional) `sprint_id` (optional) `assignee` (optional)	read
`get_task`	One task, whole: comments, checklist, files, dependencies and diagrams.	`task_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)	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)	changes or deletes
`set_task_status`	Changes a task's status (blocking requires a reason).	`task_id` `status` `block_reason` (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.	`task_id` `text`	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

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 Origin from another site is rejected with 403.
The limit is 30 requests per second per credential, with bursts of up to 60. Past it, 429 with Retry-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"}'

REST API →