Athenode MCP server

The @athenode/cli package has a built-in MCP server. It runs over stdio and exposes every CLI command except init as an MCP tool. The skills, agents and rules of the standard 'Athenode' setup use these tools to read and update your specification tree and your agent setup. In Claude Code the tools appear as mcp__athenode__<tool>, for example mcp__athenode__specs_get.

This server is Athenode's own. MCP servers that you add to your agent setup yourself are covered on the MCP servers page.

Launching the server

The server is started with this command:

npx -y @athenode/cli@latest mcp

You don't usually need to start it yourself. The standard setup includes it as an MCP server named athenode, so running npx @athenode/cli init writes it into .mcp.json, .codex/config.toml and .cursor/mcp.json (depending on the tools you choose), and your AI coding tool starts it when it needs it. That config has no environment variables, and it works as written in Claude Code, Codex and Cursor: the server finds your project root on its own (see Configuration).

init itself stays a CLI-only command: it is interactive, and it creates the config the server needs. The server writes only MCP protocol traffic to stdout.

Configuration

Setting	How it's resolved
Project root	The directory holding .athenode/config.json, resolved on every call in this order: the --project-dir <path> option; the ATHENODE_PROJECT_DIR environment variable; the server's working directory, if it holds .athenode/config.json; the first file:// MCP root of your AI coding tool that holds .athenode/config.json, if the tool supports MCP roots (Cursor does). The option wins over the variable, and empty values are ignored.
Project token	Read from .athenode/config.json. The ATHENODE_TOKEN environment variable overrides it, for example in CI. The token never appears in tool results.
API URL	The ATHENODE_API_URL environment variable, when you need a different Athenode API.

• No restart needed. The server resolves the project root and re-reads .athenode/config.json on every tool call, so running init, replacing your project token or changing your tool's workspace folders takes effect straight away. Environment variables are fixed when your AI coding tool starts the server, so changing them needs a reload of the tool or its MCP servers.
• MCP roots. Some tools, such as Cursor, start stdio servers outside your project. When the working directory has no .athenode/config.json and your tool supports MCP roots, the server asks it for its roots (usually your workspace folders) and uses the first one that holds .athenode/config.json.
• Missing config. If no project root with .athenode/config.json is found, every tool returns a NOT_INITIALIZED error telling you to run npx @athenode/cli init in the project root, or to set ATHENODE_PROJECT_DIR / --project-dir, or to add the project root as an MCP root.

Results and errors

• Results. Each tool returns the same JSON that the matching CLI command prints.
• Errors. A failed tool call returns an isError result with the CLI's structured error, including plan limit errors.
• Regeneration. Tools that change the installed setup's agents, skills, rules or MCP servers regenerate your local files, just as the CLI commands do. When an MCP config file was rewritten, the result includes a reload hint.
• Destructive tools. Deleting tools take the same force / recursive options as the CLI. Your MCP client asks you to confirm them.
• Parameters. Parameter names are camelCase, such as parentId or filePath. Pass null to clear a field. Text such as specification content or a prompt is always passed inline, never as a file path.

Tools

The server has 42 tools. Each one matches a CLI command: the tool name is the command path joined with _, with dashes replaced, so mcp-servers create becomes mcp_servers_create. Tools marked Regenerates update your local files afterwards.

Specifications

Tool	CLI equivalent	Description
specs_list	specs list	Lists specifications, optionally filtered by status and scoped to a parent or to top-level specifications.
specs_search	specs search	Full-text search across specifications (matches only).
specs_tree	specs tree	Fetches a subtree, an ancestor branch, ranked matches nested with their ancestors, or the execution order of a subtree's leaves.
specs_get	specs get	Fetches one specification with its content, status, plan and blockers.
specs_create	specs create	Creates a specification, optionally with blockers.
specs_update	specs update	Updates a specification's fields; null clears summary, content or parent.
specs_delete	specs delete	Deletes a specification and its descendants; force deletes it even when others are blocked by it.
specs_set_status	specs set-status	Sets a specification's status.
specs_set_plan	specs set-plan	Records an implementation plan, or clears it with null.
specs_get_plan	specs get-plan	Fetches a specification's implementation plan.
specs_results_list	specs results list	Lists the recorded execution results (changed files and summaries).
specs_results_create	specs results create	Records a changed file and a summary of the change.
specs_qa_list	specs qa list	Lists a specification's questions and answers.
specs_qa_add	specs qa add	Adds a question to a specification.
specs_qa_answer	specs qa answer	Answers a recorded question.
specs_blockers_list	specs blockers list	Lists the specifications that block a specification.
specs_blockers_add	specs blockers add	Adds blockers to a specification (all or nothing).
specs_blockers_remove	specs blockers remove	Removes a blocker from a specification.

Agent setups and setup files

Tool	CLI equivalent	Description
setups_list	setups list	Lists the agent setups in the project.
setups_create	setups create	Creates a new, empty agent setup.
setups_clone	setups clone	Clones an agent setup under a new name.
setups_update	setups update	Changes a setup's name or description.
setups_delete	setups delete	Deletes an agent setup.
setups_files_list	setups files list	Lists a directory of the installed setup's files.
setups_files_get	setups files get	Fetches a setup file with its content, for example settings/SETTINGS.md.
setups_files_create	setups files create	Creates a setup file, or a directory with dir: true.
setups_files_update	setups files update	Replaces a setup file's content or summary.
setups_files_delete	setups files delete	Deletes a setup file or directory; a non-empty directory needs recursive: true.

Agents

Tool	CLI equivalent	Description
agents_list	agents list	Lists the agents in the installed setup.
agents_create	agents create	Creates an agent and adds it to the installed setup. Regenerates.
agents_update	agents update	Updates an agent in the installed setup. Regenerates.
agents_remove	agents remove	Removes an agent from the installed setup. Regenerates.

Skills

Tool	CLI equivalent	Description
skills_list	skills list	Lists the skills in the installed setup.
skills_create	skills create	Creates a skill and adds it to the installed setup. Regenerates.
skills_update	skills update	Updates a skill in the installed setup. Regenerates.
skills_remove	skills remove	Removes a skill from the installed setup. Regenerates.

Rules

Tool	CLI equivalent	Description
rules_get	rules get	Fetches the installed setup's rules (AGENTS.md content).
rules_update	rules update	Replaces the installed setup's rules. Regenerates.

MCP servers

Tool	CLI equivalent	Description
mcp_servers_list	mcp-servers list	Lists the MCP servers in the installed setup.
mcp_servers_create	mcp-servers create	Adds an MCP server (stdio, http or sse) to the installed setup. Regenerates.
mcp_servers_update	mcp-servers update	Updates an MCP server in the installed setup. Regenerates.
mcp_servers_remove	mcp-servers remove	Removes an MCP server from the installed setup. Regenerates.

Manual setup

npx @athenode/cli init normally writes the athenode server into your MCP config files for you, without any environment variables, and that config works in Claude Code, Codex and Cursor. Add it by hand only if you want to set environment variables, such as an explicit project directory, or use it in a tool you didn't install into. Never commit a real project token: keep secrets out of files you commit, and use a placeholder or an environment variable instead. The env entries below are optional.

Claude Code

Claude Code starts project MCP servers in the project root, so no project directory is needed. In .mcp.json:

{
  "mcpServers": {
    "athenode": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@athenode/cli@latest", "mcp"],
      "env": {
        "ATHENODE_TOKEN": "${ATHENODE_TOKEN}"
      }
    }
  }
}

Claude Code expands ${ATHENODE_TOKEN} from your own environment, so the file never holds the token itself.

Codex

In .codex/config.toml:

[mcp_servers.athenode]
command = "npx"
args = ["-y", "@athenode/cli@latest", "mcp"]
# Optional: the directory the server starts in.
cwd = "/path/to/project"

# Optional environment variables.
[mcp_servers.athenode.env]
ATHENODE_PROJECT_DIR = "/path/to/project"
ATHENODE_TOKEN = "<your project token>"

Codex loads a project's .codex/config.toml only for trusted projects. Without cwd, the server starts in the directory Codex was launched from. If that isn't your project root and Codex doesn't provide it as an MCP root, set cwd or ATHENODE_PROJECT_DIR.

Cursor

Cursor starts stdio servers outside your project and has no cwd field, but it supports MCP roots, so the server finds your project through its workspace folders and no project directory is needed. To set it explicitly anyway, use Cursor's ${workspaceFolder} variable. In .cursor/mcp.json, with both env entries optional:

{
  "mcpServers": {
    "athenode": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@athenode/cli@latest", "mcp"],
      "env": {
        "ATHENODE_PROJECT_DIR": "${workspaceFolder}",
        "ATHENODE_TOKEN": "<your project token>"
      }
    }
  }
}

Instead of the environment variable, you can also pass the directory as an argument: "args": ["-y", "@athenode/cli@latest", "mcp", "--project-dir", "${workspaceFolder}"].

What's next

• CLI — run init and use the CLI directly
• MCP servers — add your own MCP servers to a setup
• Agent Setups — create, customize and switch between agent setups
• Supported AI tools — the MCP config file each tool gets