Connect a chat app with MCP

TOW exposes workspace tools through the Model Context Protocol (MCP), so a compatible chat app can search and update TOW without using the built-in TOW Chat screen. The external app supplies the model, conversation interface, transcript storage, and tool-approval experience.

TOW MCP uses one remote Streamable HTTP endpoint:

https://tow.example.com/api/mcp

A client can authenticate in either of two ways:

Method	Use it when	What the client can reach
Sign in with OAuth	The client asks for a server URL and opens a browser to sign you in, as hosted chat apps do.	The MCP tools only.
Personal access token	The client lets you set a custom Authorization header.	The MCP tools and the full TOW REST API.

Sign in with OAuth

Enter the endpoint URL in the client. The client discovers TOW's sign-in endpoints on its own, registers itself, and opens a TOW page in your browser.

1. Sign in to TOW if you are not signed in already. The page continues on its own once you are.
2. Check the application name and the address you will be returned to.
3. Choose the organisation the client should act in, then select Allow.

In Claude, open Settings → Connectors → Add custom connector, paste the endpoint URL, and leave the advanced OAuth fields empty.

The connection acts as you in the chosen organisation and follows your current membership, role, and project permissions on every call. It works only on the MCP endpoint: the REST API refuses its token. The client renews its access hourly in the background, and the connection lapses after 90 days without use.

Each connection appears under User Settings → Sessions → Access tokens with the client's name. Revoke it there to disconnect the client immediately.

:::note Deployment requirement OAuth clients read two discovery documents from the site root, under /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server. The deploy kit's proxy routes both to the backend from the release that introduced OAuth sign-in, so update the kit together with the images and restart the proxy once (docker compose restart proxy) so it loads the new routes. A custom reverse proxy needs the same two routes. Set mcp.oauth_enabled: false to accept personal access tokens only. :::

Create a dedicated access token

Use a token when your client supports remote HTTP MCP servers and lets you attach a custom Authorization header.

1. In TOW, open User Settings → Sessions.
2. Under Access tokens, enter a name that identifies the client, such as Desktop chat MCP.
3. Select the organisation the client should access and the shortest practical expiry.
4. Select Create.
5. Copy the token or the ready-to-paste MCP configuration before selecting Done.

TOW shows the secret only once. After it is dismissed, the Settings page retains only enough information to identify, audit, and revoke the token.

:::danger Full API authority TOW personal access tokens are not scoped to MCP. A PAT carries all of its user's privileges through the full TOW REST API. The selected organisation becomes the active organisation, but server-admin authority also remains when the user has it. Store the token as a password, never paste it into a prompt or commit it to source control, and revoke it when the client is lost or no longer used. :::

Use a separate token for each client. This makes the Last used, client, and IP metadata useful and lets you revoke one integration without interrupting another.

Configure the client

The exact file and field names depend on the chat app. A typical remote HTTP configuration looks like this:

{
  "mcpServers": {
    "tow": {
      "type": "http",
      "url": "https://tow.example.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <TOW_ACCESS_TOKEN>"
      }
    }
  }
}

Replace the URL with the public URL shown in User Settings and replace <TOW_ACCESS_TOKEN> with the one-time secret. If your client has separate endpoint and header fields, use:

Field	Value
Transport	Streamable HTTP or remote HTTP
URL	https://tow.example.com/api/mcp
Header name	Authorization
Header value	Bearer <TOW_ACCESS_TOKEN>

Do not configure browser cookies as MCP authentication. The MCP endpoint accepts a Bearer PAT and uses its current user, organisation membership, role, and project permissions on every call.

Review tool calls

After the client connects, it discovers the tools that this TOW version exposes. TOW provides bounded operational reads and content-oriented writes for accessible workspace records, plus tow_transition_ticket to move a ticket through its workflow. Administrative actions, access changes, archiving, destructive deletion, and builder configuration are intentionally not MCP tools.

A status change through tow_transition_ticket passes the same checks as moving the card in TOW: the workflow must allow the move, and the user needs the permission for it, such as closing or resolving tickets. It reaches webhooks and live boards. Automation rules treat it like a change made by TOW Chat or an Agent: a rule acts on it only when Allow automation and AI events to start this rule is on.

Clients that support them also receive:

• Prompts for common workflows: a daily brief, inbox triage, a project status report, and planning work into tickets.
• Resources for attaching context: your Today view, roadmap, inbox, and project list, plus any single item as tow://item/{type}/{ref}, for example tow://item/ticket/MAST-287. Resources return the same data as the read tools, under the same permissions.

How the agent learns to use TOW

TOW ships a usage guide for agents as an Agent Skill named tow: how the workspace is organised, which tool answers which question, reference formats, TQL syntax, and the rules for writes. The server delivers it on every channel a client may support, so you do not need to install anything:

Channel	What the client gets
Server instructions	A short summary on connect, which points the model to the full guide.
tow_guide tool	The full guide, one topic per call. Works in every client that supports tools.
MCP Skills extension	The skill as skill://tow/SKILL.md with its reference files, through skills/list and skills/get. Clients that support the extension load it like a local skill.
Resources	The same files under skill://tow/…, for clients that browse resources.

If your agent still guesses project keys, user IDs or TQL syntax, ask it to call tow_guide first.

To install the guide as a local skill instead, for example in Claude Code, read each skill://tow/… resource from the server and save it under the same relative path in a tow skill folder, such as ~/.claude/skills/tow/SKILL.md and ~/.claude/skills/tow/references/tql.md. A local copy does not update with the server, so prefer the copy the server delivers.

Keep the chat app's tool-approval setting enabled for write calls. Approving a tool call is permission to execute that specific operation; TOW still applies normal field validation and live access checks. Draft and review workflows remain drafts or reviewable changes rather than being silently published.

The external chat app owns its conversation transcript. Connecting over MCP does not create a TOW Chat conversation or require TOW's configured AI provider. Records changed through a tool still produce their normal TOW activity and audit data.

Rotate or revoke a connection

Return to User Settings → Sessions → Access tokens to review recent use or revoke a token or an OAuth connection. Revocation takes effect on the next request. To rotate a token, create a new dedicated token, update the client, verify the connection, and then revoke the old token. To move an OAuth connection to another organisation, revoke it and connect again.

If the client cannot connect

• Confirm the URL ends in exactly /api/mcp and uses the public HTTPS hostname.
• With a token, confirm the client sends Authorization: Bearer … on every MCP request. The value must start with Bearer .
• Create a new token if the secret was dismissed before it was copied.
• Check that the token is not expired or revoked and that its user still belongs to the selected organisation.
• Ask the deployment operator to verify that the reverse proxy preserves the Authorization header and does not buffer /api/mcp.
• If OAuth sign-in never opens a TOW page, open https://tow.example.com/.well-known/oauth-authorization-server in a browser. It must return JSON. A "not found" page means the reverse proxy does not route the discovery documents to the backend.
• If a hosted client cannot reach the server at all, check that the firewall admits the client vendor's published address range to both /api/mcp and the discovery and /api/oauth/ endpoints.
• A browser-based MCP client served from another site is refused with Invalid Origin header until its origin is listed in mcp.allowed_origins.

See User settings, Security and AI data controls, and Troubleshooting for related controls.