Use
Agents and MCP
Create a personal API token, connect Claude Code or any MCP client, and see what a token can and can't do.
The MCP server lets an agent such as Claude Code read and write the workspace. It is an ordinary API client: it stores nothing, holds no token between requests, and every call goes through the same permission checks as the web app. Self-hosted installations serve it at APP_URL/mcp with nothing to configure.
Create a token
Agents authenticate with a personal API token, which acts as the person who made it. In the app, open the user menu and choose API tokens.
- Name the token, after the agent that will use it.
- Choose Read only (the default) or Read and write.
- Untick any module the agent doesn't need.
- Pick an expiry: 30, 90, 180 or 365 days. 90 is the default; nothing lasts forever.
The token, which starts knw_, is shown once along with ready-to-copy setup commands. Only its hash is stored. The same page lists your tokens, shows when each was last used, and lets you revoke them.
Connect a client
Claude Code, against your server:
claude mcp add --transport http knotworking https://knot.example.com/mcp \
--header "Authorization: Bearer knw_…"
Any client that supports remote MCP servers with custom headers works the same way: the URL, and the token in an Authorization: Bearer header.
Local (stdio) clients
For a client that launches a local process, such as Claude Desktop, build the server from a checkout and point it at your installation. The API isn't reachable from outside, but the web app proxies it under /api.
{
"mcpServers": {
"knotworking": {
"command": "node",
"args": ["/absolute/path/to/knotworking/apps/mcp/dist/stdio.js"],
"env": {
"KNOTWORKING_API_URL": "https://knot.example.com/api",
"KNOTWORKING_API_TOKEN": "knw_…",
"KNOTWORKING_DEFAULT_WORKSPACE": "acme"
}
}
}
}
Run pnpm --filter @knotworking/mcp build first, so dist/stdio.js exists.
What a token can do
- A read token can only make GET requests. Write tools answer
token_read_only. - A write token acts as its owner, so their role still applies: a guest's write token is read-only.
- The agent only sees tools for modules that are active, that its person can read, and that the token allows.
- Tokens never reach admin routes or anyone's personal calendar. Agents can read workspace meetings but not change them.
- Delete tools cover tasks, projects, documents and time entries only, each behind
confirm: true. - Writes land in the sync log like anyone's, attributed to the token's owner.
Actions that need a person
Some actions refuse tokens and need a signed-in person. They come in two kinds.
| Kind | Examples | Can be opened to agents |
|---|---|---|
| Operational actions | Sending, closing or cancelling a purchase order; recording waste; adjusting stock; posting a stocktake; cancelling a batch | Yes, per workspace, by an owner or admin |
| Sign-offs and approvals | Approving suppliers, recipes, SOPs and HACCP plans; QA lot release; training sign-off | Never |
| Records that attest a person did something | SOP acknowledgement, cleaning and calibration records, completed checks | Never |
| Ledger corrections and safety | Reversing stock movements, roll calls, kiosk devices and PINs | Never |
Operational actions are off by default. An owner or admin opens them under Settings, API access, signed in with their own account, and each token must also name the action in its own list. Every attempt through an opened action is written to an audit log, refusals included, and the token's owner and the workspace's admins are notified when one succeeds. A token can also carry a maximum purchase order value.
Security
- Workspace text is written by other people and can contain instructions aimed at an agent. The server tells agents to treat it as data, which lowers the risk but doesn't remove it. Use read tokens for agents that read other people's writing, and check what write-capable agents do.
- Give each agent its own token, so you can revoke one without the others.
- Revoking a token, deleting its user or changing their password stops it at once.
- Serve the MCP endpoint over HTTPS so tokens don't cross the network in clear text.
- Reaching the server by an address that isn't
APP_URLgets403 Invalid Host; add it toMCP_ALLOWED_HOSTS.
Rate limits
Rate limits, batch size and allowed hosts are covered in Configuration. Over a limit, calls get 429 with Retry-After.