> For agents: connect to the AoTwin MCP server at https://app.aotwin.io/mcp to read and change tickets and projects. Setup guide: https://aotwin.io/docs/mcp.md. Index of all docs: https://aotwin.io/llms.txt.

# MCP server

Connect your AI assistant to AoTwin to file, find and update tickets from the chat.

## Overview

MCP is a standard way for AI assistants to use other tools. AoTwin speaks it, so the assistant you already use can file tickets, find and read them, comment, change their status and assign them, without leaving the chat.

There is one address for every assistant: `https://app.aotwin.io/mcp`. You sign in to AoTwin once when the assistant asks. There is no key to copy. The assistant acts as you, in the workspace you pick, and everything it does shows as yours.

Filing or editing a ticket never starts AoTwin. Only assigning a ticket to AoTwin does, and that uses [credits](https://aotwin.io/docs/credits). MCP is available on every plan, the Free plan included, but the Free plan cannot assign tickets to AoTwin.

## Configure

Choose your assistant and follow its steps. Each one ends with a sign-in to AoTwin in your browser.

### claude.ai and the Claude apps

1. Go to [Customize > Connectors](https://claude.ai/customize/connectors).
2. Choose **Add custom connector**.
3. Paste the address `https://app.aotwin.io/mcp` and sign in.

On a Team or Enterprise plan, an owner adds it once under **Organization settings > Connectors**. Then each person connects from **Customize > Connectors** with their own account.

### Claude Code

Run this once in a terminal:

```bash
claude mcp add --transport http aotwin https://app.aotwin.io/mcp
```

Then run `/mcp` in Claude Code and sign in.

### Cursor

Choose [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=aotwin&config=eyJ1cmwiOiJodHRwczovL2FwcC5hb3R3aW4uaW8vbWNwIn0=) and sign in when Cursor asks. Or paste this into your `mcp.json`:

```json
{"mcpServers":{"aotwin":{"url":"https://app.aotwin.io/mcp"}}}
```

### VS Code

Run **MCP: Add Server** from the Command Palette, choose HTTP and paste the address. Sign in when VS Code asks. Or paste this into `.vscode/mcp.json`:

```json
{"servers":{"aotwin":{"type":"http","url":"https://app.aotwin.io/mcp"}}}
```

### Codex

Run these once in a terminal, then sign in in the browser:

```bash
codex mcp add aotwin --url https://app.aotwin.io/mcp
codex mcp login aotwin
```

### Zed

Open **Settings > AI > MCP Servers**, choose **Add Server**, then **Add Remote Server**, and sign in when Zed asks. Or paste this into your settings file:

```json
{"context_servers":{"aotwin":{"url":"https://app.aotwin.io/mcp"}}}
```

### Other assistants

Most take the address directly. If yours only runs local commands, give it this one instead. It needs Node.js.

```bash
npx -y mcp-remote https://app.aotwin.io/mcp
```

### The sign-in screen

When the assistant sends you to AoTwin, the page says which assistant **wants to use AoTwin** and lists what it will be allowed to do:

- See tickets, projects and people in the workspace.
- Create, edit, comment on and close tickets as you.
- Assign tickets, including to AoTwin, which starts work and uses credits.

Choose **Allow** to continue or **Cancel** to stop. The page also says where it will send you back. If that is your own computer, only allow it if you started the connection yourself.

## Basics

### What your assistant can do

- **File a ticket.** Describe it in plain words. The assistant fills in the title, the details and the project.
- **Find and read tickets.** Ask what is assigned to you, what is waiting on review, or what a ticket says.
- **Update tickets.** Comment, change the status, assign, reopen or close.
- **Hand one to AoTwin.** Only when you ask.

### Things to ask

- "What's waiting on me in AoTwin?" reads your inbox: questions from AoTwin and work ready to review.
- "File a ticket: the footer links overlap on phones." files it for nobody. If someone already filed something similar, you get that ticket back.
- "Turn these meeting notes into tickets. Show me the list before you file anything." lets you check the list first.
- "What's in review in WEB, and who is it assigned to?" filters by project and status.
- "Read AO-123 and tell me what AoTwin changed." sums up the ticket and the work done on it.
- "Hand AO-123 to AoTwin." is the only one here that starts AoTwin, and it uses credits.

### The tools it gets

Read tools:

| Tool | What it does |
| --- | --- |
| `whoami` | Says which person and workspace the connection acts as. |
| `list_requests` | Finds tickets by text, project, assignee or status. |
| `get_request` | Reads one ticket, with what AoTwin changed and the activity so far. |
| `inbox` | Lists what needs you: questions from AoTwin and work ready to review. |
| `list_projects` | Lists the workspace's projects and their keys. |
| `list_people` | Lists the people in the workspace. |

Change tools:

| Tool | What it does |
| --- | --- |
| `create_request` | Files a ticket. This never starts AoTwin. |
| `update_request` | Edits a ticket's title, description or page. |
| `comment` | Adds a comment as you. It can answer a question from AoTwin. |
| `assign` | Assigns a ticket. Assigning to AoTwin starts the work and uses credits. |
| `set_status` | Moves a ticket to another status. |
| `reopen` | Reopens a ticket that is done or canceled. |
| `close_request` | Cancels a ticket, and stops AoTwin if it is working on it. |

AoTwin's word for a ticket is sometimes "request", which is why the tools are named that way. They mean the same thing.

A few rules the tools follow:

- Filing never assigns to AoTwin. File first, then use `assign`.
- If a similar ticket already exists, `create_request` returns it instead of filing a duplicate. Ask for it again with `force` to file anyway.
- `list_requests` and `inbox` return up to 100 results at a time and give a cursor for the next page.
- Only the person who asked, or an admin, can close a ticket. A ticket AoTwin holds can only be canceled, so reassign it first to change its status.

## Read-only connections

If your assistant lets you choose scopes, ask for read only when you sign in. The connection then gets only the read tools, and your account lists it as **Read only**. The change tools are not offered to it, and the assistant is told the connection is read-only.

To switch from read only to full access, remove AoTwin from the assistant and connect again, this time allowing changes.

## Use more than one workspace

Each connection acts in one workspace. If you belong to several, the sign-in screen has a **Workspace** menu. Pick the workspace for that connection.

To use a different workspace, remove AoTwin from your assistant and connect again, then pick the other one.

## Disconnect

1. Open your [account](https://app.aotwin.io/account).
2. Under **Connected AI tools**, find the assistant. Each row shows the workspace, whether it is **Read only** or **Can make changes**, and when it was last used.
3. Choose **Disconnect** and confirm.

The connection stops working straight away. Your tickets are not touched.

## Troubleshooting

**It won't connect.** Remove AoTwin from your assistant, add it again and sign in once more. That does not touch your tickets.

**You use `mcp-remote`.** Also delete the `~/.mcp-auth` folder, which holds its saved sign-in, and update Node.js.

**You are not in a workspace.** The sign-in page says so. Open AoTwin, set a workspace up, then connect again.

**An assign to AoTwin is refused.** The Free plan does not include AoTwin. The message links to **Settings > Plan**.

**The ticket waits after you assigned it.** If the project has no code connected, the assistant tells you the ticket is waiting for GitHub. See [GitHub](https://aotwin.io/docs/github).

Still stuck? [Write to us](https://aotwin.io/#contact).

## FAQ

<details>
<summary>What is MCP?</summary>

A standard way for AI assistants to use other tools. AoTwin speaks it, so the assistant you already use can work with your tickets.

</details>

<details>
<summary>Is there a key to copy?</summary>

No. Sign in to AoTwin once when the assistant asks, and it acts as you, in your workspace.

</details>

<details>
<summary>Which plans include it?</summary>

Every plan, Free included.

</details>

<details>
<summary>Will it start AoTwin by itself?</summary>

No. Filing and editing a ticket never start it. Only assigning a ticket to AoTwin does, and that uses credits.

</details>

<details>
<summary>Can I connect it read-only?</summary>

Yes, if your assistant lets you choose scopes: ask only for read when you sign in. It then gets only the tools that read, and your account shows the connection as read only.

</details>

<details>
<summary>How do I use another workspace?</summary>

Each connection acts in one workspace, which you pick when you sign in. Remove AoTwin from your assistant and connect again to pick a different one.

</details>

<details>
<summary>How do I disconnect it?</summary>

Open your account in AoTwin, find **Connected AI tools** and choose **Disconnect**. It stops working straight away.

</details>