External MCP

Connect another agent, such as Claude Code or Codex, to OpenDucktor through MCP. It can then create, find, read, and update your tasks.

Connect a clientCopy Anchor Link

Run OpenDucktor on the same computer as the client. Install Bun.

1. Add the server to your client.

   Claude CodeCodexOther clients

   Copy Text

   claude mcp add openducktor -- bunx @openducktor/mcp

2. Restart the client. It now lists the odt_* tools.

The server finds the running OpenDucktor app by itself. The agent gets your workspaces from odt_get_workspaces, and gives a workspaceId in each call. So one client can work in all your workspaces.

Set a default workspaceCopy Anchor Link

When a client works in one repository, you can give the server a default workspace. The agent can then leave out workspaceId.

1. In OpenDucktor, open Settings, then Repositories. Select your repository, and copy the Workspace ID from Configuration.

   

2. Add --workspace-id and the ID after @openducktor/mcp. For example, in the repository folder:

   Copy Text

   claude mcp add openducktor -- bunx @openducktor/mcp --workspace-id fieldnotes

The agent can still give another workspaceId. To keep it in the default workspace, also set ODT_FORBID_WORKSPACE_ID_INPUT to true.

Server optionsCopy Anchor Link

Give an option after @openducktor/mcp, or set its environment variable in the MCP config of your client. The option wins over the variable.

• Default workspace: --workspace-id <id>, or ODT_WORKSPACE_ID. The agent can leave out workspaceId. The server stops if OpenDucktor has no workspace with this ID. See Set a default workspace.
• One workspace only: ODT_FORBID_WORKSPACE_ID_INPUT set to true or 1. With a default workspace, it removes workspaceId from every tool, so the agent can use only that workspace.
• Tools: ODT_ALLOWED_TOOLS, with tool names separated by commas, such as odt_search_tasks,odt_read_task. The server offers only these tools. The default is the task tools.
• Address: --host-url <url>, or ODT_HOST_URL. The server connects to this address of OpenDucktor, and not to the address that it found.
• Token: --host-token <token>, ODT_HOST_TOKEN, or ODT_HOST_TOKEN_FILE with the path of a file that holds the token. Use it with the address.

For example, this entry keeps a client in the workspace fieldnotes:

{
  "mcpServers": {
    "openducktor": {
      "command": "bunx",
      "args": ["@openducktor/mcp"],
      "env": {
        "ODT_WORKSPACE_ID": "fieldnotes",
        "ODT_FORBID_WORKSPACE_ID_INPUT": "true"
      }
    }
  }
}

Without --host-url, the server reads the address and the token of the running app from runtime/mcp-bridge.json, in the folder of OpenDucktor: ~/.openducktor, or the folder of OPENDUCKTOR_CONFIG_DIR.

Create a task from the clientCopy Anchor Link

Ask the client, for example:

File an OpenDucktor bug: moving a note drops its tags. Priority P1.

Approve the odt_create_task call if the client asks. The card shows in the Backlog lane, with the Bug and P1 badges.

Task toolsCopy Anchor Link

The server also lists odt_apply_workflow_event and odt_set_pull_request. In Spec, Plan, Build, the Builder uses odt_apply_workflow_event to send the events build-blocked, build-resumed, and build-completed, which change the status of a task. build-blocked requires a note. The Builder uses odt_set_pull_request to save the pull request of a task. Your client can call both tools too.

Fix connection problemsCopy Anchor Link

If the client shows no odt_* tools, read the MCP server log of the client. The first error names the cause. For each error and its fix, see Troubleshooting.

NextCopy Anchor Link