# Connect an AI assistant with MCP

> Connect Claude, ChatGPT, Cursor or another MCP client to Troopy, and choose what it may do.

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.

| Way        | Best for                                                   | What it may do                                   |
| ---------- | ---------------------------------------------------------- | ------------------------------------------------ |
| Sign in    | Claude, ChatGPT, Cursor and other apps that support OAuth. | The scopes that the app asks for, and you allow. |
| An API key | Claude Code, scripts, and apps that send a header.         | The scopes that you pick for the 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.

> [!NOTE]
> An app that asks for no scope in particular asks for every scope. The page then lists them all.

### Cursor

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

```json
{
  "mcpServers": {
    "troopy": { "url": "https://troopy.ai/api/mcp" }
  }
}
```

## 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**:

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

> [!WARNING]
> A key acts as you. Keep it out of code, chats and URLs. Viewers, approvers and guests make no keys.

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

```bash
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](/docs/cli).

## What the assistant can do

The server has a tool for most operations of the API, such as `troopy_whoami`. The
[API reference](/docs/api#operations) 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](/docs/api#scopes) 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

| What you see                     | Why                                                          | What to do                                                      |
| -------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------- |
| "This app can't connect"         | The app sent a request that Troopy cannot take.              | Read the reason under it. Add the server again in the app.      |
| "You aren't in a workspace yet." | Your account has no workspace that can let an app in.        | Open Troopy and finish setup, or ask for an invite.             |
| `unauthorized`                   | The key or the sign-in is wrong, or someone revoked it.      | Sign in again, or make a new key.                               |
| `forbidden`                      | The key lacks a scope, or your role cannot do the change.    | Make a key with the scope, or ask an owner or admin.            |
| `rate_limited`                   | Too many calls of one tool in a minute.                      | Wait the seconds of `Retry-After`, then try again.              |
| `not_connected`                  | The tool reads a service that the workspace did not connect. | Ask an owner or admin to connect it in **Settings** > **Apps**. |

## Related

- [API reference](/docs/api)
- [Use the Troopy CLI](/docs/cli)
- [Manage your account](/docs/account)
- [Limits and defaults](/docs/limits#workspace-and-api)