Connect an AI assistant with MCP

The MCP server lets an AI assistant, such as Claude, ChatGPT or Cursor, work in Troopy as you. It can list your tasks, read your docs, or give work to a teammate. This page tells how to connect an assistant and how to choose what it may do.

Before you begin

• The address of the server is https://troopy.ai/api/mcp. It takes streamable HTTP.
• You need a workspace where you are not a guest. A guest lets no app into a workspace.
• An assistant connects in one of two ways: you sign in to Troopy from it, or you give it an API key.

Each way acts as you, in one workspace. Your role still limits it: a viewer, for example, changes nothing over MCP.

Sign in from an assistant

1. In the assistant, add a custom connector or an MCP server with the address https://troopy.ai/api/mcp.
2. The assistant opens Troopy. Log in if Troopy asks.
3. Read the page Connect and the name of the app. It will be able to lists what the app asks for.
4. Pick the Workspace.
5. Select Allow. Troopy sends you back to the app.

Select Deny to say no. The app gets nothing. A sign-in that the app keeps using stays on. An app that renews its sign-in within 60 days never needs a new one.

Cursor

Add Troopy to the mcp.json file of Cursor. Cursor then asks you to sign in.

1{2  "mcpServers": {3    "troopy": { "url": "https://troopy.ai/api/mcp" }4  }5}

Connect with an API key

1. Open Settings > API keys.
2. Type the Key name, and pick the Scopes that the assistant needs.
3. Select Create key, then Copy key. Troopy will not show the key again.
4. Give the key to the assistant in the Authorization header.

For Claude Code, Use it from Claude Code on the same page gives the whole command. Select Copy MCP command:

claude mcp add --transport http troopy https://troopy.ai/api/mcp --header "Authorization: Bearer tr_live_..."

Without the header, Claude Code signs in through the browser. Run /mcp in Claude Code to start the sign-in.

A local server

Some assistants start each MCP server on your computer, over stdio. The troopy-mcp package is such a server. It sends each call to the API of Troopy with your key.

claude mcp add troopy --env TROOPY_API_KEY=tr_live_... -- npx -y troopy-mcp

The CLI does the same with npx -y troopy mcp. See Use the Troopy CLI.

What the assistant can do

The server has a tool for most operations of the API, such as troopy_whoami. The API reference names the MCP tool of each operation that has one.

• A tool runs the same checks as the API: the scopes, the rate limits and the checks of the input.
• A tool that changes data takes an idempotencyKey. A second call with the same key never runs the work twice.
• A tool that starts work of a teammate, such as a message, answers at once. The work goes on in Troopy.
• A call that waits for a yes, such as an email to send, still waits in Needs you. With agents:write, the assistant can decide it as you, within your role.

Ask the assistant for what you want in your own words. It picks the tools. For example: "List my tasks that need me", or "Ask the Researcher to compare our three biggest competitors".

Choose what it may do

A scope is a part of Troopy that a key or an app may read or change, such as tasks:read or brain:write. The API reference lists every scope.

• Give a key only the scopes that its work needs. A key for reports needs only scopes that read.
• An app keeps the scopes that you allowed. To give it others, sign it out, then sign in again from the app.
• A tool that needs a scope that the key lacks answers forbidden, and names the scope.

Sign an app out

1. Open Settings > Security.
2. Find the app under the apps that you signed in to Troopy with.
3. Select Revoke. The app is signed out at once.

To stop a key, open Settings > API keys, and select Revoke on the key. A new password also signs out each app.

Problems

Related

• API reference
• Use the Troopy CLI
• Manage your account
• Limits and defaults