The Atono MCP server connects AI tools, such as Claude, Cursor, or VS Code, to your Atono workspace. Once connected, your AI tool can read and update stories, bugs, epics, subtasks, and their AI context, and it can look up related information such as timeboxes, team workflows, and your Glossary, all using your own workspace access.

Atono hosts the MCP server for you, so there's nothing to install, and you connect each AI tool by logging in to Atono. If you need to run the server locally instead, you can connect with the Docker MCP server.

Overview

Here are a few examples of what your AI tool can do once it's connected:

Stories:

• "Add a story for the API team to paginate search results and assign it to Max."
  • The AI finds the right team and user, creates the story with a user story statement and acceptance criteria, and assigns it.
• "Move STORY-123 to Development and assign it to Sam Taylor."
  • It updates the story's workflow step and assigns it.
• "Review the acceptance criteria in STORY-456 and suggest improvements."
  • The AI retrieves the story, reviews the criteria, and proposes changes. When you're ready, it can apply them directly.

Bugs:

• "Log a bug for the login timeout issue affecting production and assign it to the backend team."
  • The AI creates the bug with a summary, reproduction steps, expected and actual behavior, and applies the team and environment.
• "Fix BUG-789 and move it to Test once done."
  • After applying the fix, the AI moves the bug to 'Test' and adds a plain-English summary of the change to the bug description.

Epics:

• "Create an epic for the Q3 checkout redesign and add STORY-101, STORY-104, and STORY-110 to it."
  • The AI creates the epic, adds the listed stories, and confirms the result.
• "What's the status of EPIC-12?"
  • The AI retrieves the epic and summarizes its stories, their workflow steps, and what's left to do.
• "Rewrite the user story statements on EPIC-12 to reflect the new persona we're targeting."
  • The AI replaces the epic's user story statements with the updated set.

Subtasks:

• "Break STORY-456 into subtasks for the frontend and backend work."
  • The AI creates subtasks on the story, one per piece of work.
• "Mark the backend subtask on STORY-456 as done and assign the frontend one to Priya."
  • The AI updates the relevant subtasks' workflow step and assignee.

Linked items:

• "Link STORY-101 to BUG-202."
  • The AI creates a link between the two items so they appear as related in the web app.

Timeboxes:

• "What's planned for the Q2 launch timebox?"
  • The AI retrieves all stories and bugs in the timebox and summarizes what's included, their workflow steps, and team assignments.

AI context:

• "Check the design decisions on STORY-456 before we start implementation."
  • The AI retrieves the design decisions recorded during authoring (rationale, tradeoffs, and scoping choices), so implementation stays aligned with the original product intent.
• "Check the investigation notes on STORY-456 and continue from there."
  • The AI retrieves research and findings saved from previous work on the story and uses them to recommend next steps.
• "Check the change summary on BUG-789 and suggest what still needs to be done."
  • The AI retrieves a record of implementation changes already made, so it can continue work without duplicating or conflicting with what's already been done.

Other:

• "Does 'timebox' mean the same thing as 'sprint' in our glossary?"
  • The AI checks the Glossary and confirms the defined term, helping keep terminology consistent in stories, bugs, and documentation.
• "Write release notes for STORY-45, STORY-52, and STORY-73."
  • The AI retrieves each story, summarizes their acceptance criteria and outcomes, and drafts release notes that describe what changed and why.

Together, these actions use Atono MCP tools, the individual commands your AI tool can call to read or update data in your workspace.

Connect with the hosted MCP server

You only need to do this once per AI tool.

Before you begin

Make sure you have:

• An AI tool that supports remote MCP servers, such as Claude, Claude Code, Cursor, Devin Desktop, OpenAI Codex, or VS Code with GitHub Copilot.
• The hosted MCP server turned on for your workspace. It's on by default, but a Workspace Owner or Administrator can turn it off. For more details, see Turn the hosted MCP server on or off.

If you already use the Docker MCP server, we recommend disabling or removing it in your AI tool once you've added the hosted MCP server.

Copy your Atono MCP URL

Your Atono MCP URL is shown on your Integrations page.

1. Click the circular icon with your initials in the top-right corner of the web app, then select Integrations. For more details, see Manage your integrations.
2. Under 'MCP connections', next to 'Atono MCP URL', click the copy icon.

Add the Atono MCP server to your AI tool

You add the Atono MCP server to your AI tool as a custom MCP server. The steps are similar in most AI tools, although each one names things slightly differently.

1. In your AI tool, open its settings and find the section for MCP servers. Some tools call these connectors.
2. Select the option to add a custom MCP server or custom connector.
3. If you're asked for a transport type, select HTTP. Many tools select it by default.
4. Paste your Atono MCP URL, and give the server a name if asked, such as Atono.
5. Save or connect. Your AI tool opens Atono in your browser, where you log in if needed and authorize the connection.

Some AI tools, especially coding tools that run in a terminal, add MCP servers with a command instead of a settings page. Check your AI tool's documentation for adding a remote MCP server, and use your Atono MCP URL where it asks for the server URL.

Example: Claude

1. In Claude, go to Settings > Connectors.
2. Click Add, then select Add custom connector.
3. In the 'Add custom connector' dialog, enter a name, such as Atono, paste your Atono MCP URL, and click Continue.
4. Under 'Authentication' and 'OAuth client', leave the options Claude selects for you, then finish adding the connector.
5. In the connectors list, next to Atono, click Connect. If Claude asks you to confirm in your browser, click Continue connecting, then authorize the connection.

On Claude Team and Enterprise plans, only an organization owner can add a custom connector, so 'Add custom connector' is unavailable to other members. Once an owner adds the Atono connector, it appears in each member's connectors list, where they click Connect and authorize their own connection.

Authorize the connection

1. If you're asked for your workspace, enter the workspace name from your Atono URL, then click Continue. For example, if you open Atono at acme.atono.io, enter acme.
2. If you aren't logged in to Atono, log in to your workspace as usual, including with SSO if your organization uses it. Afterward, you continue to the authorization page.
3. On the authorization page, under 'You're authorizing as', check that the account and workspace are correct. If they aren't, click Not you?. You're logged out of Atono so you can log in with a different account, and then you return to the same authorization page.
4. Review what your AI tool will be able to do, then click Allow access. To stop without connecting, click Cancel.

After you allow access, the connection appears under 'Authorized MCP connections' on your Integrations page. If you click Cancel, no connection is created and your AI tool reports that authorization was denied.

What an authorized AI tool can do

When you authorize a connection, the AI tool can act in your workspace with your account. It can:

• Read and edit stories, bugs, epics, and subtasks
• Log activity under your name
• Access and update AI context

It can't do anything your own account doesn't have permission to do.

Manage your MCP connections

Your Integrations page lists the MCP connections you've authorized under 'Authorized MCP connections'. Each connection shows its name, when it was created, and when it was last used.

When you authorize a new connection, Atono names it after the AI tool if the tool provides its name, for example, 'Claude Desktop'. If it doesn't, the connection is named 'MCP'. When a name is already in use, a number is added, such as 'Claude Desktop 2' or 'MCP 2'.

Rename an MCP connection

Renaming a connection can help you tell them apart, for example if you've connected the same AI tool on two computers.

1. On your Integrations page, next to the connection, click the ellipsis (...) icon, then select Rename.
2. In the 'Rename MCP connection' dialog, enter a new name. Each of your connection names must be unique.
3. Click Rename MCP connection.

Revoke an MCP connection

Revoke a connection when you no longer use an AI tool with Atono, or if you think a connection is being used without your permission.

1. On your Integrations page, next to the connection, click Revoke.
2. In the confirmation dialog, click Revoke connection to confirm, or click X to cancel.

The AI tool loses access to Atono immediately, and the connection is removed from your list. Revoking doesn't undo any changes the AI tool already made, and it doesn't affect your other connections or your API keys. To use the AI tool with Atono again, add the Atono MCP URL and authorize it as a new connection.

Turn the hosted MCP server on or off

The hosted MCP server is on by default for every workspace. Workspace Owners and Administrators can turn it off if they don't want team members connecting AI tools this way.

This setting only affects the hosted MCP server. Team members using the Docker MCP server with an API key can keep using it.

Turn off the hosted MCP server

1. In the web app, go to Settings, and under 'Integrations', click Hosted MCP.
2. Click Disable.
3. In the confirmation dialog, click Disable Hosted MCP to confirm, or click X to cancel.

When you turn it off, AI tools can no longer connect to your workspace through the hosted MCP server. Team members' existing connections stay listed on their Integrations page, but the AI tools can't access Atono, and requests return an error. If someone tries to authorize a new connection, they see a 'Hosted MCP isn't enabled' message.

Turning off the hosted MCP server doesn't undo changes AI tools already made, and it doesn't affect API keys or the Docker MCP server.

Turn on the hosted MCP server

1. In the web app, go to Settings, and under 'Integrations', click Hosted MCP.
2. Click Enable.

Connect with the Docker MCP server

The Docker MCP server runs locally using Docker and communicates with your AI tool through the Model Context Protocol (MCP). It authenticates with an Atono API key, so use it if your AI tool needs to run the server locally or can only connect with an API key. For more details, see Compare the hosted and Docker MCP servers.

Quick start

To connect your AI tool to Atono:

1. Install Docker Desktop and make sure it's running.
2. Get your Atono API key.
3. Add the Atono MCP server to your AI tool.
4. Restart your AI tool.
5. Confirm it's connected.

You only need to set this up once per tool.

Prerequisites

Make sure you have the following:

1. Docker Desktop (version 27.0 or later)

Used to run the Atono MCP server locally.

Download at: https://www.docker.com/products/docker-desktop/

What is Docker?

Docker is the tool that runs the Atono MCP server on your computer. The MCP server is distributed as a Docker image, a packaged version of the server and everything it needs to run. When you add the Atono MCP configuration to your AI tool, that configuration tells Docker which image to use and how to start it.

When your AI tool starts the Atono MCP server, Docker automatically downloads the latest image from Docker Hub and runs it locally. You don't need to download or configure the image yourself. Just install Docker Desktop and keep it running while you use your AI tool.

For more details, see Update the Docker MCP server.

Check that it's installed (optional)

Run the following in your terminal (macOS/Linux) or command prompt (Windows). If Docker is installed correctly, you'll see a version number.

docker --version

2. An Atono API key

Used to authenticate your MCP server with your Atono workspace.

For more details, see Manage API keys.

3. An MCP-enabled tool

Such as Claude Code, Cursor, VS Code, Devin Desktop, or GitHub Copilot.

Configuration

After you've installed Docker, retrieved your Atono API key, and confirmed that your AI tool supports MCP, you're ready to connect it to your workspace.

Each client has its own way of adding an MCP server, but they all follow the same basic pattern:

• Point to the Atono MCP Docker image
• Provide your API key
• Restart the tool

You'll find setup details for several popular tools below. If yours isn't listed, start with the general example and refer to your tool's documentation for the specific configuration format it requires.

General

Most MCP-enabled tools include an 'Add MCP Server' dialog or allow you to edit a small JSON configuration file.

{
  "atono": {
    "command": "docker",
    "args": [
      "run",
      "--pull=always",
      "-i",
      "--rm",
      "-e",
      "X_API_KEY",
      "atonoio/atono-mcp-server:latest"
    ],
    "env": {
      "X_API_KEY": "YOUR_ATONO_API_KEY"
    }
  }
}

Notes:

• command: the program used to launch the server (Docker).
• args: the parameters passed to Docker to run the container.
• env: environment variables passed to the container, including your API key.

Some tools may use slightly different field names, for example:

• serverUrl or url (for HTTP connections instead of command-based ones)
• headers instead of env for authentication tokens

Atono will continue to maintain compatibility with standard MCP fields as the protocol matures.

Claude Code

1. Run the following command in your terminal:

claude mcp add --transport stdio atono \
  --env X_API_KEY=YOUR_ATONO_API_KEY \
  -- docker run --pull=always -i --rm -e X_API_KEY atonoio/atono-mcp-server:latest

2. Replace YOUR_ATONO_API_KEY with your API key.
3. Run /mcp in a Claude Code session to confirm that atono appears in the list of servers.

For more details, see Claude Docs on Installing MCP servers.

Claude Desktop

1. Go to Settings > Developer > Local MCP Servers > Edit config.
2. Open the Claude configuration file, claude_desktop_config.json.
3. Add the Atono MCP server configuration.

If the file is empty, copy and paste the following:

{
  "mcpServers": {
    "atono": {
      "command": "docker",
      "args": [
        "run",
        "--pull=always",
        "-i",
        "--rm",
        "-e",
        "X_API_KEY=YOUR_ATONO_API_KEY",
        "atonoio/atono-mcp-server:latest"
      ]
    }
  }
}

If the file already has other settings, add the mcpServers section (with a comma after the previous section):

{
  "existingSettings": "...",
  "mcpServers": {
    "atono": {
      "command": "docker",
      "args": [
        "run",
        "--pull=always",
        "-i",
        "--rm",
        "-e",
        "X_API_KEY=YOUR_ATONO_API_KEY",
        "atonoio/atono-mcp-server:latest"
      ]
    }
  }
}

4. Replace YOUR_ATONO_API_KEY with your API key.
5. Save the file and restart Claude Desktop.
6. If you return to Settings > Developer > Local MCP Servers > Edit config, you should see atono listed.
7. Start a new chat and ask a question, such as "What Atono MCP tools are available?" You should see a list of the tools that allow Claude Desktop to manage your Atono workspace.
8. When you next ask a question that requires workspace context (for example, "Find BUG-456 in Atono"), Claude detects the Atono MCP server and prompts you to allow access, either Always allow or Allow once. You might see this prompt again when using other tools.

Cursor

One-step install

If you're using Cursor, click the button below to install the Atono MCP server. Cursor loads the configuration automatically, so no JSON editing is required.

If you'd prefer, you can also install Atono from the official Cursor MCP directory.

Once installed, the server appears under 'Tools & MCP', and Cursor can use it to read and update Atono data when you ask.

Manual configuration

1. Go to Cursor > Settings > Cursor Settings.
2. On the Settings page, in the side menu, click Tools & MCP.
3. Click Add Custom MCP. This opens the mcp.json file.
4. Add the following:

{
  "mcpServers": {
    "atono-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--pull=always",
        "-i",
        "--rm",
        "-e",
        "X_API_KEY=YOUR_ATONO_API_KEY",
        "atonoio/atono-mcp-server:latest"
      ]
    }
  }
}

5. Replace YOUR_ATONO_API_KEY with your API key.
6. Save the file and return to the 'Cursor Settings' page. You should see atono-mcp-server listed and enabled.
7. Click # tools enabled under the server name to view its available tools.

Devin Desktop (formerly Windsurf)

1. Go to Devin > Settings > Devin settings.
2. On the Settings page, go to Cascade > MCP Servers, and click Open Devin MCP Marketplace.
3. In Devin's MCP Marketplace, click the Settings (gear) icon to open the mcp_config.json file in your editor.
4. Add the following:

{
  "mcpServers": {
    "atono-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--pull=always",
        "-i",
        "--rm",
        "-e",
        "X_API_KEY=YOUR_ATONO_API_KEY",
        "atonoio/atono-mcp-server:latest"
      ]
    }
  }
}

5. Replace YOUR_ATONO_API_KEY with your API key.
6. Save the file and restart Devin Desktop.
7. If you return to your list of MCP servers, you should now see the custom atono-mcp-server server listed and enabled. Click the server to view its available tools.

OpenAI Codex

Codex supports MCP servers via a configuration file stored at ~/.codex/config.toml.

1. Add the following to your file:

[mcp_servers.atono]
command = "docker"
args = ["run", "--pull=always", "-i", "--rm", "-e", "X_API_KEY", "atonoio/atono-mcp-server:latest"]

[mcp_servers.atono.env]
X_API_KEY = "YOUR_ATONO_API_KEY"

2. Replace YOUR_ATONO_API_KEY with your API key.

Codex automatically starts the Atono MCP server when you open a session that references it.

For more details, see OpenAI's Model Context Protocol documentation.

VS Code (GitHub Copilot)

1. Open the Copilot Chat panel in VS Code.
2. Click the Configure Tools (tools) icon next to the model selector.
3. In the 'Configure Tools' dialog, click the Add MCP Server (plug) icon to open a list of connection types.
4. Select Docker Image.
5. When prompted, enter the Docker image name:

atonoio/atono-mcp-server:latest

6. Press Enter.
7. When asked to confirm, click Allow.
8. When prompted to enter the 'Server ID', leave the default value (atono-mcp-server) and press Enter.
9. Select where to install the server:
   • Workspace adds the connection for your current project only (recommended).
   • Global makes the connection available in all VS Code workspaces.
10. When prompted to trust the server, click Trust.
11. When the .vscode/mcp.json file opens, add the following:

{
  "mcpServers": {
    "atono-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--pull=always",
        "-i",
        "--rm",
        "-e",
        "X_API_KEY=YOUR_ATONO_API_KEY",
        "atonoio/atono-mcp-server:latest"
      ]
    }
  }
}

12. Replace YOUR_ATONO_API_KEY with your API key.
13. In the 'MCP Servers' panel, click the Restart (restart) icon next to atono-mcp-server to apply your changes.
14. When prompted again, click Trust.
15. In Copilot Chat, type a question such as "What is my Atono configuration?"
16. When Copilot asks to use the Atono MCP server, click Allow.

Update the Docker MCP server

When a new version of the Atono MCP server is released, no manual steps are required.

To update:

1. Close your AI tool.
2. Make sure Docker is running.
3. Reopen your AI tool.

Your MCP configuration uses --pull=always, so Docker automatically downloads the latest version when the server starts.

If you want to check available versions or confirm the latest release, you can view the Atono MCP server on Docker Hub.

Stop or remove the Docker MCP server

Press Ctrl + C in your terminal to stop the server.

To remove the image completely:

docker rmi atonoio/atono-mcp-server:latest

Compare the hosted and Docker MCP servers

Both servers give your AI tool the same Atono MCP tools. The main differences are where the server runs and how you authenticate.

Check that it's working

These steps work for both the hosted and Docker MCP servers.

1. Open your AI tool.
2. Start a new chat or session.
3. Ask, "What Atono MCP tools are available?"
4. Allow access if prompted.

Your tool should provide a list of Atono tools.

If you're using the Docker MCP server and your AI tool can't connect, check that Docker Desktop is open and running.

If you're using the hosted MCP server and see a message saying 'Hosted MCP isn't enabled', the hosted MCP server has been turned off for your workspace. Ask a Workspace Owner or Administrator to turn it on, or use the Docker MCP server instead. If your AI tool is connected but every Atono tool returns an error, the hosted MCP server may have been turned off for your workspace.

If you see 'Unable to continue' while authorizing, the connection request is invalid or has expired. Return to your AI tool and start the connection again, and if it keeps happening, contact Atono Support. If a connection that used to work stops working and the hosted MCP server is on, check your Integrations page to see whether it's still listed under 'Authorized MCP connections', and reauthorize it if it isn't.

Tracking AI-performed actions

When the Atono MCP server performs actions on behalf of a user, such as creating a story, moving it between workflow steps, or updating a bug, it marks those actions so they can be identified as being completed by the MCP server.

This marking allows Atono to record the action in the Activities view as 'Performed by MCP server', helping teams understand which updates came from AI-connected tools rather than direct user actions in the web app.

Security notes

The Atono MCP server only exposes a limited set of actions defined by Atono and can't access data outside your workspace. Some actions, such as updating acceptance criteria or moving items between workflow steps, modify Atono data directly and may not be reversible.

Hosted MCP server

• Each connection is authorized with your Atono login, so there's no API key to store in your AI tool's configuration.
• Review your authorized connections on your Integrations page from time to time, and revoke any you no longer use.

Docker MCP server

• Treat your Atono API key like a password.
• Avoid committing keys to repositories or shared config files.