MCP servers

The Model Context Protocol (MCP) lets AI coding agents call external tools and data sources, such as a browser, an issue tracker or your own internal services. An agent setup's MCP servers are exported to Claude Code, Codex and Cursor together with its agents, skills and AGENTS.md content, so everyone using the setup gets the same tools.

What MCP is

An MCP server exposes tools that a coding agent can call while it works. The agent connects to the server either by starting it as a local process (the stdio transport) or by calling it over the network (the http and sse transports). You describe each server once in your agent setup, and Athenode writes it into the MCP configuration of every coding tool it exports to.

Adding MCP servers

Open your agent setup in the web app and go to its MCP servers tab. The main Add MCP server button opens the MCP catalog if you can import from it, and the manual form otherwise. Its menu also offers Add from catalog and Add manually.

Adding servers from the MCP catalog requires editor or owner access to a setup that belongs to your project. The shared default setup can't be edited, so clone it first — see Agent Setups. If you don't have that access, Add from catalog is disabled.

From the MCP catalog

The Add MCP server page lets you search the MCP catalog and add several servers in one go:

Search for the servers you need and select one or more of them.
For each selected server, choose an install option, for example a package that runs locally or a remote endpoint.
Fill in the Required variables listed for that option. Secret values are never stored: they become placeholders that you set in your own environment (see Secrets below).
Import the selected servers together.

Some servers ask you to sign in with OAuth. That sign-in happens in your coding tool itself, not in Athenode.

Manually

Choose Add manually to enter a server yourself. Pick a transport, then fill in the fields it needs: a command, arguments and environment variables for stdio, or a URL and headers for http and sse. The Field reference below describes each field.

Exporting

Changes in the web app reach your machine the next time you run athenode init, or any CLI command that regenerates your files. Athenode merges the setup's servers into your existing MCP configuration files, so servers you added yourself are kept.

Note

A server marked Not exported to Codex is left out of the Codex configuration and is still exported to Claude Code and Cursor. This applies to sse servers and to http servers that use a placeholder in the URL, or a header value that contains a placeholder but isn't exactly ${VAR} (or, for the Authorization header only, exactly Bearer ${VAR}). Placeholders with a default value, such as ${VAR:-default}, and headers mixing a placeholder with other text therefore aren't exported.

Field reference

Setup MCP servers tab

These are the fields of a server added on the setup's MCP servers tab.

Field	Description
Name	The server's name. It must be unique within the setup, and it's the name your coding tools show for the server.
Transport	How the coding agent connects to the server: `stdio` (a local process), `http` or `sse` (a remote endpoint).
Command	`stdio` only. The program that starts the server, such as `npx`.
Arguments	`stdio` only. The arguments passed to the command, in order.
Environment variables	`stdio` only. Variables set for the server's process. Use `${VAR}` placeholders for secrets.
URL	`http` and `sse` only. The address of the server's endpoint.
Headers	`http` and `sse` only. HTTP headers sent with every request, for example an authorisation header. Use `${VAR}` placeholders for secrets.

Agent-level MCP servers

An agent can also list its own MCP servers in the mcpServers field on its Claude Code metadata tab. These entries support every field above, plus the following.

Field	Description
Transport	In addition to `stdio`, `http` and `sse`, the `ws` (WebSocket) transport is available.
OAuth	The client ID, callback port and scopes the coding tool uses to sign in to the server.
Timeout	How long the coding tool waits for the server, in milliseconds.
Always load	A flag passed through to the coding tool unchanged.
Headers helper command	A command the coding tool runs to produce request headers, instead of fixed header values.

Secrets

Never put real tokens, keys or passwords into an MCP server. Use a ${VAR} placeholder instead, and set the variable in the environment where Claude Code, Codex or Cursor actually runs. Athenode never stores the values.

Warning

For servers on the setup's MCP servers tab, Athenode rejects a literal value in any environment variable or header whose name looks secret. A name looks secret when one of its parts, separated by _, - or ., is TOKEN, KEY, APIKEY, SECRET, PASSWORD, AUTH or AUTHORIZATION, ignoring case, or when it's the Proxy-Authorization header. Only whole parts count: GITHUB_TOKEN and x-api-key look secret, while MONKEY, AUTHOR and OAUTH_CLIENT_ID don't. Use a ${VAR} placeholder for these.

Catalog installs turn secrets into placeholders automatically, so you only need to set the variables listed on the Add MCP server page.
Missing variables: after athenode init or any other command that regenerates your files, the CLI lists the placeholder variables that are unset or empty in its own environment. Placeholders with a default value, such as ${VAR:-default}, aren't reported. The CLI's environment may differ from the one your coding tool runs in, so make sure the variables are set wherever Claude Code, Codex or Cursor runs.

MCP servers, skills and agents

Importing skills

Skills often rely on particular MCP servers. When you import skills, the MCP servers for the imported skills panel lists every server they use and its status: Already in setup, Found in catalog, a number of catalog matches, or Not in catalog. Use its Add actions to add the missing servers straight away.

Missing MCP servers

The setup page shows a Missing MCP servers notice for servers that the setup's skills explicitly require but that the setup doesn't have yet. You can add each server from the notice or dismiss it. Dismissals are remembered per user and per setup, in this browser only. Use Show dismissed to see dismissed servers again.

Per-agent MCP servers

An agent's mcpServers entries can either reference a setup-level server by its name or define an inline server of the agent's own. Keep inline server names distinct from setup-level ones; Athenode won't let you add a setup-level server with the same name as an agent's inline server.

What's next

AGENTS.md — the shared instructions exported with your setup
Agent Setups — create, customise and switch between agent setups
CLI — manage MCP servers from the terminal with the mcp-servers commands