MCP server (AI assistants)
The sol2flow MCP server lets AI assistants work with your boards and tasks: "what's on my plate today?", "create a task for the login bug and assign it to Ben", "move PRD-12 to Done and log 1h 30m". It speaks the Model Context Protocol, which Claude Desktop, Claude Code, Cursor, VS Code and many other assistants understand.
The server uses the REST API with your personal API key. So the assistant can do exactly what you can do in the app, nothing more: your roles, the key's access (Full access or Read only), your organization's plan and the workspace's REST API switch all apply, exactly as for the API.
What you need
- An API key: account menu (bottom left) → API keys → Create API key (API keys). Choose Full access if the assistant should change things, Read only if it should only look. The key is shown once: copy it.
- The REST API must be available: on sol2flow cloud, your organization's plan includes it; on your own instance, an administrator has Allow API keys on (Instance settings); and the workspace has REST API on (Settings → Workspace → Access & integrations, Workspaces).
- One of these:
- sol2flow cloud: nothing else. Use the hosted server at
https://mcp.sol2flow.com/mcp. - On your computer: Node.js 22 or later. Your assistant starts the server with
npx -y @sol2flow/mcp; this works for sol2flow cloud and for your own instance. - Your own instance: the server as a Docker container next to sol2flow (Self-hosted).
- sol2flow cloud: nothing else. Use the hosted server at
Connect your assistant
Replace sf_… with your key. For your own instance, add SOL2FLOW_URL with its address (for example
https://flow.example.com); without it, the server uses sol2flow cloud.
Claude Code
# the hosted server (sol2flow cloud)
claude mcp add --transport http sol2flow https://mcp.sol2flow.com/mcp --header "Authorization: Bearer sf_…"
# or on your computer, for any instance
claude mcp add sol2flow --env SOL2FLOW_URL=https://flow.example.com --env SOL2FLOW_API_KEY=sf_… -- npx -y @sol2flow/mcp
Claude Desktop
Settings → Developer → Edit Config opens claude_desktop_config.json. Add:
{
"mcpServers": {
"sol2flow": {
"command": "npx",
"args": ["-y", "@sol2flow/mcp"],
"env": { "SOL2FLOW_URL": "https://app.sol2flow.com", "SOL2FLOW_API_KEY": "sf_…" }
}
}
}
Restart Claude Desktop. sol2flow's tools appear in the tools menu of a new chat.
Cursor
In ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project), either the same mcpServers entry as for
Claude Desktop, or the hosted server:
{
"mcpServers": {
"sol2flow": { "url": "https://mcp.sol2flow.com/mcp", "headers": { "Authorization": "Bearer sf_…" } }
}
}
VS Code
In .vscode/mcp.json (or MCP: Open User Configuration for all workspaces). VS Code asks for the key once and keeps
it in its secret storage, so it isn't written into the file:
{
"inputs": [{ "type": "promptString", "id": "sol2flow-key", "description": "sol2flow API key", "password": true }],
"servers": {
"sol2flow": {
"type": "http",
"url": "https://mcp.sol2flow.com/mcp",
"headers": { "Authorization": "Bearer ${input:sol2flow-key}" }
}
}
}
On your computer instead: "type": "stdio", "command": "npx", "args": ["-y", "@sol2flow/mcp"], "env": { "SOL2FLOW_URL": "https://flow.example.com", "SOL2FLOW_API_KEY": "${input:sol2flow-key}" }.
Other assistants
Any MCP client works: either start npx -y @sol2flow/mcp with the environment variables SOL2FLOW_API_KEY (and
SOL2FLOW_URL), or connect to an HTTP server (https://mcp.sol2flow.com/mcp or your own) with the header
Authorization: Bearer sf_….
Claude.ai and ChatGPT connectors (in the browser) sign in with OAuth instead of a key. That comes in a later version; until then, use one of the assistants above.
Self-hosted
With your own sol2flow, you can run the HTTP server next to it, so everyone on your instance can connect to one address
with their own key. The image is ghcr.io/sol2flow/mcp (amd64 and arm64). For example in the Docker Compose file that
runs sol2flow (its service called app):
services:
mcp:
image: ghcr.io/sol2flow/mcp:latest
restart: unless-stopped
read_only: true
environment:
SOL2FLOW_URL: http://app:3000 # sol2flow as reachable from this container
ALLOWED_HOSTS: mcp.example.com # the host name people connect to
TRUST_PROXY_HOPS: '1' # one reverse proxy in front
FORWARD_CLIENT_IP: 'true'
ports: ['127.0.0.1:3005:3000']
Put it behind your reverse proxy with HTTPS (like sol2flow itself, see Reverse proxy);
people then use https://mcp.example.com/mcp.
| Setting | Default | What it does |
|---|---|---|
SOL2FLOW_URL | https://app.sol2flow.com | Your sol2flow. Fixed by you: people can't point the server elsewhere |
ALLOWED_HOSTS | — | The host names (or host:port) the server answers to, comma-separated. Set it: it protects against DNS rebinding |
ALLOWED_ORIGINS | localhost only | Browser-based assistants: the origins allowed to call the server (* for any). Desktop and command-line assistants don't need it |
TRUST_PROXY_HOPS | 0 | The number of proxies in front, to find the person's IP address in X-Forwarded-For |
FORWARD_CLIENT_IP | false | Pass that IP address on to sol2flow, so its rate limits and "last used from" see the person, not the server |
SOL2FLOW_WORKSPACE | — | A default workspace (its slug) |
READ_ONLY | false | Hide every tool that changes something |
LOG_LEVEL | info | debug adds a line per API request |
LOG_FILE | — | Also write the log to daily files next to this path (e.g. /data/logs/mcp.log; mount /data/logs writable for user 1001) |
SENTRY_DSN | — | Error tracking (Sentry, Bugsink or GlitchTip); or SENTRY_DSN_FILE |
The container runs as user 1001, works with a read-only file system, answers GET /healthz and has a health check. It
keeps no data: you can run several, restart or replace it at any time.
What the assistant can do
| Tool | What it does |
|---|---|
whoami | Your account, the key, the sol2flow version and your workspaces |
list_workspaces, list_boards, get_board | Workspaces, boards, and a board with its lists and tasks |
search | Boards and tasks by name, key (PRD-12) or text, like the search in the app |
list_tasks | Tasks by board, list, assignee, label, text, due dates or last change |
get_task | A task with its description, checklist, links and latest comments |
list_labels, list_people | Labels and workspace members |
list_time_entries, get_timer | Logged time and your running timer |
list_notifications, list_my_invitations | Your notifications and pending invitations |
create_task, update_task, move_task | Create, change (fields, labels, assignees, list) and move tasks, also to another board |
archive_task, unarchive_task | Archive a task and bring it back |
add_comment, add_checklist_items, update_checklist_item | Comments and checklists |
link_tasks, unlink_tasks | Blocks, blocked by, relates to, duplicates |
log_time, start_timer, stop_timer, update_time_entry | Time tracking |
mark_notifications_read, respond_to_invitation | Notifications and invitations |
create_board, create_list, create_label | Boards, lists and labels |
There is no tool to delete anything: archiving is the safe way, and it can be undone. Sharing, members, webhooks, imports and attachments stay in the app.
Two ready-made prompts are included, shown by many assistants as commands: plan_my_day (a plan from your tasks, due dates and notifications) and board_standup (what moved on a board, what is in progress, blocked or overdue).
Referring to things: you and the assistant can use what you see in the app. Tasks by key (PRD-12, also the old key
of a task moved to another board) or by their link; boards by key or name; lists and labels by name; people as "me",
by username or name. Descriptions and comments are Markdown both ways.
The default workspace: when you are in one workspace, the assistant always uses it. With several, it searches them
all for a task key, and otherwise asks which one; or set a default with SOL2FLOW_WORKSPACE (on your computer) or
?workspace=<slug> at the end of the HTTP address (https://mcp.sol2flow.com/mcp?workspace=acme).
Read-only mode
To let an assistant only look, use a Read only key: every change is refused with a clear message. From sol2flow 1.8,
a server on your computer also recognizes the read-only key and hides the tools that change something, so the assistant
doesn't even try. You can hide them yourself for any key: READ_ONLY=true (on your computer) or ?read_only=1 at the
end of the HTTP address.
API limits
Every tool call is one or more API requests, and they count like any other use of the API: 600 requests per 10
minutes per key, at most 120 of them changes, and on sol2flow cloud your plan's daily API requests. Most tools take one request; get_task takes three (the
task, its links and comments), get_board two to four, create_task and update_task a few more to look up lists,
labels and people. Looking up a task key or a board name costs one search the first time; the result is remembered for
10 minutes. When a limit is reached, the assistant is told how long to wait.
Troubleshooting
The assistant gets a message it can act on, and usually tells you what's wrong. The common ones:
| Message says | What to do |
|---|---|
| "sol2flow refused the API key" | The key is wrong, expired or revoked. Create a new one and update it in your assistant |
| "No sol2flow API key is configured" | Set SOL2FLOW_API_KEY, or the Authorization: Bearer header for the HTTP server |
| "API keys are switched off on this sol2flow instance" | An administrator has Allow API keys off (Instance settings) |
| "API access is switched off for this workspace" | A workspace admin turns REST API on under Access & integrations |
| "The organization's plan doesn't include the REST API" | An owner or admin of the organization upgrades the plan |
| "The organization's workspaces are read-only" | The subscription is past due or ended; reading still works |
| "This API key is read-only" | Use a key with Full access, or keep it read-only on purpose |
| "You don't have permission for this" | Your role doesn't allow it, e.g. viewers and guests can't edit |
| "Not found, or you don't have access to it" | Check the key or name; sol2flow never says whether something exists if you can't open it |
| "The task is archived and read-only" | Unarchive it first (the assistant can, with unarchive_task) |
| "sol2flow's rate limit is reached" / "daily API requests" | Wait the time the message names |
| "may or may not have been applied" | A change got no answer in time. Check the task before asking again: changes are never repeated automatically |
| "This sol2flow instance … is too old" | The instance needs an update for that tool |
| The tools don't appear | Restart the assistant after changing its configuration; check that npx (Node.js 22+) is installed |
Privacy
- The MCP server stores nothing: no keys, no tasks, no content. Each request to the hosted server brings its own key and is forgotten when it's answered.
- Its log has the tool's name, the outcome, the time it took, the IP address the request came from (HTTP server) and the first 8 characters of the key (the public part shown in the list of API keys) — never the key, what the assistant asked for, or what sol2flow answered.
- What the assistant sends to its AI provider is between you and that provider: the MCP server only answers the questions the assistant asks, with what your key may see. Use a Read only key, or limit what you ask, if that matters for a workspace.