MCP

Elyra speaks the Model Context Protocol in both directions:

As a client it uses MCP servers, including the ones you already configured for Claude Code, Cursor, or VS Code.
As a server (elyra --mode mcp) it lets other MCP hosts delegate work to Elyra.

Using MCP servers

MCP support ships with Elyra as the bundled @elyracode/mcp package. There is nothing to install. With no servers configured it adds no tools and costs nothing. The standalone binary builds cannot load bundled packages yet; there, run elyra install npm:@elyracode/mcp once.

Where servers come from

Elyra reads the configuration you already have. Later entries win when two define the same server name.

Scope	File	Format
user	`~/.claude.json` (top level and the entry for the current project)	Claude Code
user	`~/.cursor/mcp.json`	Cursor
user	`~/.elyra/agent/mcp.json`	Elyra
project	`.vscode/mcp.json`	VS Code (`servers`)
project	`.cursor/mcp.json`	Cursor
project	`.mcp.json`	Claude Code
project	`.elyra/mcp.json`	Elyra

Project files are only read in trusted projects, because they define commands that run on your machine.

{
  "mcpServers": {
    "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/" },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
    },
    "linear": { "url": "https://mcp.linear.app/sse", "directTools": true }
  }
}

command, args, env, cwd define a local (stdio) server. url and optional headers define a remote one. type may be stdio, http, or sse. It is inferred when omitted.
${VAR} and ${VAR:-default} expand from your environment. A server that references an unset variable is skipped with a message.
disabled: true switches a server off.
timeout sets the per-request timeout in milliseconds. The default is 60000.
directTools: true also exposes each of the server's tools as its own Elyra tool, named mcp__<server>__<tool>.

A stdio server receives a minimal environment (PATH, HOME, and similar) plus the env you configure. Your shell's API keys are not passed on unless you list them.

How the agent uses them

Instead of putting every server's tool schemas into every request, Elyra adds two tools:

mcp_search finds tools by keyword and returns their names and input schemas.
mcp_call calls a tool by server and name.

The tools block stays the same no matter how many servers and tools you have. That keeps the context small and the prompt cache warm.

Servers start lazily, the first time a tool list or tool is needed. Tool lists are cached in ~/.elyra/agent/mcp-cache.json, so searching usually needs no running server at all. When a connected server reports that its tools changed, the cache updates. For directTools servers the new tools are registered with defer, so they do not invalidate the prompt cache in the middle of a conversation.

Child agents started by @elyracode/swarm reuse the parent session's connections through a local broker, instead of starting their own copies of every server.

Logging in to remote servers

Remote servers that require OAuth are logged in with:

/mcp login <server>

Elyra registers itself with the server's authorization server, opens your browser, and receives the redirect on http://127.0.0.1:53687/mcp/callback. Tokens are stored in ~/.elyra/agent/extension-credentials.json with 0600 permissions and refresh automatically. If the agent calls a server that needs login in interactive mode, Elyra offers to start the login.

A server whose headers contain an Authorization header is treated as managing its own auth, and Elyra does not run OAuth for it.

The /mcp command

/mcp                       status of every server, plus skipped files and config problems
/mcp login <server>        OAuth login for a remote server
/mcp logout <server>       forget stored tokens
/mcp refresh [server]      reconnect and refetch tool lists
/mcp disable <server>      switch a server off (saved in ~/.elyra/agent/mcp-state.json)
/mcp enable <server>
/mcp reload                re-read all configuration files

Turning MCP off

Set "mcp": false in ~/.elyra/agent/settings.json to stop loading the bundled package. --no-extensions also skips it. If you install @elyracode/mcp yourself, for example to pin a version, the bundled copy steps aside.

Elyra as an MCP server

elyra --mode mcp serves Elyra over stdio for MCP hosts such as Claude Desktop, Cursor, or another agent:

{
  "mcpServers": {
    "elyra": { "command": "elyra", "args": ["--mode", "mcp"], "cwd": "/path/to/project" }
  }
}

Start it in the project directory. For hosts without a cwd option, use a wrapper such as "command": "sh", "args": ["-c", "cd /path/to/project && exec elyra --mode mcp"].

It exposes three tools:

Tool	What it does
`elyra_task`	Runs the Elyra agent on a task in the project directory. The default `read-only` mode can only read and search. `edit` mode can also edit files and run commands. Returns the answer, changed files, cost, and a session id you can continue with `elyra --session <id>`.
`elyra_review`	Reviews uncommitted changes, by default with a model from a different vendor than Elyra's current model.
`elyra_decisions`	Lists the project's recorded architecture decisions.

Tasks run one at a time, and each gets a fresh session. Tool activity is reported as MCP progress notifications, which keeps hosts with request timeouts from giving up on long tasks. Project trust applies as in every non-interactive mode. Start with --trust-project if the host should load the project's own packages and MCP configuration.

Elyra never loads its own MCP server back into itself. A configured server that runs elyra --mode mcp is skipped with a message.