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 v1 uses a remote Streamable HTTP endpoint and a personal access token (PAT):

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

Your client must support remote HTTP MCP servers and let you attach a custom Authorization header. OAuth and hosted clients that cannot set custom headers are not supported in this release.

Create a dedicated access token

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. Administrative actions, access changes, destructive deletion, and builder configuration are intentionally not MCP tools.

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. 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.

If the client cannot connect

• Confirm the URL ends in exactly /api/mcp and uses the public HTTPS hostname.
• Confirm the client sends Authorization: Bearer … on every MCP request.
• 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 the client only offers OAuth, use a client that supports custom headers for now. OAuth support is planned for a later release.

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