MCP Integration

Connect an AI such as Claude Code, Codex, ChatGPT, Cursor, or Claude Desktop to Addness (MCP integration), and the AI can read and write your Addness goals, ToDos, comments, and more.

For first-timers: For people who created a new organization and people who joined an organization by invitation, the goal page includes "Set up Addness." On its "1. Connect your AI to Addness" row, press "Ask AI" → "Open in Claude Code" (or "Open in Codex"), and the AI proceeds in order, starting with connecting to Addness (→ Goal page). For steps starting from installing the AI app, see Install an AI app and connect it to Addness. This article explains only the MCP integration.

Send the request to your AI

Just send this request to the AI you use.

Please set up Addness MCP (https://vt.api.addness.com/mcp).

The AI proceeds where it can and guides you only where your operation is needed. Only the browser sign-in approval, please do yourself when the AI guides you to it.

What the AI becomes able to do

Whichever AI you connect from, it reads and writes the same goal tree in the same organization.

If it stops partway: steps by tool

If setup stops on permissions or authentication, show the AI the steps below, or continue yourself.

ChatGPT (official plugin)

Type “@Addness” in ChatGPT or select Addness from the app list. Press “Connect”, sign in to Addness, and press “Allow”. Available on Free. Writes require confirmation. You can only connect an existing Addness account (you can't sign up from ChatGPT).

Claude Code (terminal)

1. Add Addness MCP (with --scope user, so it's usable from any project)

claude mcp add --transport http --scope user addness https://vt.api.addness.com/mcp

1. Sign in to Addness (when the browser opens, approve with your Addness account)

claude mcp login addness

1. Check the connection (done if addness appears in the list; you can also check from /mcp inside Claude Code)

claude mcp list

Codex (CLI)

You can use it just by signing in to Addness in the browser. Creating an API key isn't needed (old Codex doesn't support OAuth, so update to the latest version before running).

1. Add Addness MCP (the browser opens automatically, so approve with your Addness account. The settings are saved to ~/.codex/config.toml)

codex mcp add addness --url https://vt.api.addness.com/mcp

1. Check the connection (done if Auth is OAuth. If sign-in didn't start, run codex mcp login addness)

codex mcp list

Cursor

1. Open ~/.cursor/mcp.json and add the following setting (if you have other servers, add just the addness entry)

{
  "mcpServers": {
    "addness": {
      "url": "https://vt.api.addness.com/mcp"
    }
  }
}

1. In Cursor's Settings → Tools & MCP, press Connect for addness and approve with your Addness account in the browser

Claude Desktop

Add a remote MCP not via a config file but as a custom connector.

1. Open Customize → Connectors and choose + → Add custom connector
2. Set the name to Addness and the URL to https://vt.api.addness.com/mcp and save (on Team / Enterprise, organization configuration by the Owner is required)
3. Press Connect for Addness and approve in the browser (you can enable it per conversation from Connectors)

Other MCP-compatible clients

Any MCP client that supports Streamable HTTP and OAuth can connect.

1. Set the server name to addness and the transport to Streamable HTTP
2. Specify https://vt.api.addness.com/mcp as the connection target
3. Sign in to Addness from the client's authentication button; done once the tool list is retrieved

Check that it's connected

Ask your AI: "Show me my Addness organizations." If it answers with the names of the organizations you belong to, it's connected. You can also ask "Show me my ToDos in Addness" and check that your ToDos come back.

If you belong to more than one organization, ask the AI "Switch Addness to the organization <organization name>" before you start working. The AI switches the organization it works in (switch_organization). If it's already connected to that organization, nothing changes. The organization you switch to carries over to the same AI's next conversations.

If it answers that there are no Addness tools, or that authentication is needed, see If it doesn't connect.

To hand it over from the screen: "Ask AI"

Instead of asking in words, you can also hand it over from the ✦ ("Ask AI") on the right of a goal's row (at mobile widths, the row's "…" → "Ask AI").

• Work on it: The AI reads that goal's context and moves it forward as-is
• Brainstorm: The AI sorts things out while talking with you and proposes child goals. Only the ones you OK are created
• Ask: Write what you want to know and hand it over, and the AI reads the goal and answers. It doesn't change the goal

Press "Open in Claude Code," "Open in Codex," or "Open in ChatGPT," and the AI opens with an instruction that includes the goal's URL and how to proceed. With "Copy instruction," you can paste it into another AI like Cursor and use it. Set the "Instruction handoff" under "AI" in Personal settings, and it opens in one click without choosing every time. For a detailed explanation of what happens, see the Goal page.

How this differs from the external integration API

MCP integration lets your AI read and write Addness under your own signed-in account. If you only need your own systems to read your organization's members and to-dos for today, use the External integration API (read-only), which is called with a key fixed to the organization. External integration keys can't be used with MCP. The external integration API is available only to organizations that Addness has enabled.

If it doesn't connect

These are common problems and how to fix them. How to install the AI app and connect it is in Install an AI app and connect it to Addness.

The Addness tools aren't available

• You connected it, but the AI says there are no Addness tools: On a computer, in Claude Code or Codex, Right after connecting, the tools don't show up until you reopen the AI app. Quit the app, open it again, pick the same conversation and send "continue". Closing the window doesn't quit the app. On a Mac, press Command + Q. On Windows, close it with Alt + F4, and if its icon is still in the bottom-right corner of the screen, right-click it and choose "Quit". In a terminal, press Ctrl + C twice to quit, then go back to the same conversation with claude --resume (for Codex, codex resume)
• It still says there are none after reopening: Claude Code may not load the Addness tools until it uses them. Tell the AI "Find the Addness tools and use them"
• It asks for permission every time it uses a tool, and stops: Ask the AI "Set it up so you can use the Addness tools without asking me each time." In Claude Code, this adds mcp__addness to the allow list in the settings file (~/.claude/settings.json)
• You removed the Addness tools to free up context: While they're removed, the AI can't read your Addness goals or to-dos. Keep them connected while you work with Addness. If you removed them, ask the AI "Turn the Addness tools back on" and reopen the app
• Addness does not appear in Claude or ChatGPT in the browser: Connect Addness through the official plugin in ChatGPT or a custom connector in browser Claude. See Use Addness on a phone only.

Sign-in doesn't go through, or the connection drops

• The sign-in screen doesn't open: Ask the AI "Start the Addness sign-in and show me the URL." Paste the URL it shows into your browser, open it, and press "Allow". If the "Allow" screen doesn't appear or a different browser opens, see "If it doesn't work" in Install an AI app and connect it to Addness
• You pressed "Allow" but got an error: If the sign-in screen stays open for a while, you get an error such as "The authorization code could not be generated." Have the AI start the sign-in again, and press "Allow" right away on the screen that opens
• It worked before, but now it asks you to sign in, or keeps asking you to sign in: The connection to Addness expires after 90 days. It is cut off earlier than 90 days in the following cases. Reconnecting from the same AI app cuts off that app's previous connection. Each person can have up to 20 connections, and beyond that, the connection that has gone unused the longest is cut off first (if you use several computers or AIs, old connections may be cut off here). Ask the AI "Sign in to Addness again" and press "Allow" in the browser
• You mixed up your work and personal accounts: The AI connects to the account shown as "Signed in as …" on the "Connect to Addness MCP" screen. Check the email address before you press "Allow". If you connected the wrong account, sign in to Addness in the browser with the right account, then ask the AI "Sign in to Addness again"

It's connected to a different organization

• The AI says the target wasn't found, or it's reading goals from another organization: The AI connects to the organization you had selected in Addness in the browser when you pressed "Allow". If you belong to more than one organization, ask the AI "Switch Addness to the organization <organization name>." When you give it a goal's URL, switch to the organization that goal is in first

It stops on Windows

• It stops while connecting with Codex, or requests from your phone stop: Installing the Codex app alone may not make the codex command available on your computer. On Windows, this has been the cause. Ask the AI "Check whether the codex command works, and install it if it doesn't." If pressing "Open in Codex" doesn't open Codex, press "Copy instruction", paste it into Codex and send it
• Sign-in to Addness doesn't finish in Codex for Windows: Update Codex to the latest version and sign in again. If it still doesn't finish, you can also connect with Claude Code

<a id="mobile-only"></a>

Use Addness on a phone only

• ChatGPT app: Type “@Addness” in ChatGPT or select Addness from the app list. Press “Connect”, sign in to Addness, and press “Allow”.
• Claude app: In Safari, open claude.ai → Customize → Connectors → ＋Add → Add custom connector → Name Addness and URL https://vt.api.addness.com/mcp → Connect and allow. Turn on Addness in the Claude app, paste the instructions, and send.
• Continue on a computer: Follow You can't ask from your phone to send work to AI on your computer.

<a id="phone-pc-relay"></a>

You can't ask from your phone

“You can't ask from your phone” describes how to send work to AI on a computer. For using only a phone, see “Use Addness on a phone only”.

"Ask AI" in the Addness mobile app sends your request to Claude Code or Codex on your computer. The Addness desktop app (→ Web app and desktop app) needs to be installed on your computer, signed in with the same Addness account and kept open, and your computer needs to be awake. Use the same organization on your phone and in the desktop app. To get this ready, ask the AI on your computer to do the goal "Ask your AI from your phone," and the AI will set it up. On a company Windows computer, the desktop app may not be allowed to run.

• "Your computer's AI isn't connected yet" appears: Your computer isn't set up yet. Open Addness on your computer, press "Ask AI" (✦) on "Ask your AI from your phone", and go through it
• "Will start when your PC wakes up" stays and nothing happens: Your computer is asleep, or the desktop app is closed. Wake the computer and open the app, and it starts. The request is cancelled after 24 hours
• "Codex was not found on the PC" appears: The codex command isn't installed on your computer. Ask the AI on your computer "Install the codex command," then reopen the desktop app
• You use the Codex that comes inside the ChatGPT app on a Mac: The desktop app can't find the Codex inside the ChatGPT app. Ask the AI on your computer "Install the codex command," then reopen the desktop app (the desktop app looks for Codex only in .local/bin in your home folder and in the places where the terminal looks for commands)
• "Choose a working folder in Addness on the PC" or "No working folder is chosen in Addness on the PC" appears: Open "リモート操作" (Remote control) in the settings of the desktop app on your computer, and choose the folder the AI should work in under "作業フォルダ" (Working folder) at the top. Until you choose one, requests reach neither Claude Code nor Codex
• "Update Addness on the PC" appears: The desktop app on your computer is an old version. Update it to the latest version, then send again
• "“Accept from phone” for Codex is off in Addness on the PC" appears: Open "リモート操作" (Remote control) in the settings of the desktop app on your computer, and turn on "スマホから受け付ける" (Accept from phone) in the "Codex" section (choose a "作業フォルダ" (Working folder) first)
• It doesn't reach Claude Code: Check that the Claude app on your phone is signed in with the same Claude account as your computer

It still doesn't connect

• Nothing you try connects: Antivirus software or your company network may be blocking the connection to Addness. In some cases, it connected after vt.api.addness.com was excluded from scanning in the software's settings. On a company computer, ask your IT team
• Nothing here gets you any further: Attach a screenshot of the screen where it stopped and contact us from "Questions about Addness" on the help home page