Docs / Integrations

MCP servers

Specialists can carry tools from MCP servers. One file declares the servers, and each entry names the specialists that get its tools.

What MCP is here

MCP, the Model Context Protocol, is a standard way for a program to offer tools to a model: an issue tracker's search, a wiki's pages, a chat's messages. ivralo connects to MCP servers you declare and hands their tools to the specialists you name. Nobody else carries them, so each specialist's tool list stays short.

mcp.json

The servers are declared in mcp.json in your home. IVRALO_MCP_CONFIG points at another file.

{
  "mcpServers": {
    "everything": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "env": { "API_KEY": "${EVERYTHING_KEY}" },
      "agents": ["analyst"],
      "timeout_seconds": 30
    },
    "wiki": {
      "url": "https://wiki.example.com/mcp",
      "headers": { "Authorization": "Bearer ${WIKI_TOKEN}" },
      "agents": ["librarian"]
    }
  }
}

The core fields are the ones other MCP clients use, so a server block from an MCP server's README pastes straight in. ivralo's own fields sit in the same block.

Key	What it sets
`command`, `args`	a local server started as a process; `args` is a list of strings
`url`	a remote server's endpoint
`transport` (or `type`)	`stdio`, `sse` or `streamable-http`; `http` is an alias
`env`	environment variables for a local server
`headers`	HTTP headers for a remote server
`agents`	the preset keys that carry the server's tools
`enabled`	`false` keeps the entry but attaches it to nobody
`timeout_seconds`	read timeout; 30 by default
`include_tools`, `exclude_tools`	expose only some tools, or hide some
`tool_name_prefix`	a prefix for the tool names, against collisions

An entry has exactly one of command or url. The transport defaults to stdio for a command and streamable-http for a URL; a command with any other transport is refused. An unknown key is a problem, not a silent no-op, because a typo would otherwise change what the server does.

Secrets stay in the environment

${VAR} placeholders in env, headers and url are filled from the environment when the file is loaded. The value lives in your .env, never in mcp.json. A placeholder whose variable is unset is a problem, unless the server is disabled.

The per-server agents list

agents is the grant for that server. It names presets by key: analyst, librarian, coder, or a specialist that a local skill brings with it. Each key is checked against the team; an unknown one is a problem that lists the valid keys.

A few agents never carry MCP tools, whatever the file says:

Who	Why
the main agent	`main` is not a key `agents` accepts
every agent under the strict profile	`IVRALO_PROFILE=strict` removes every outward grant, and a server's reach cannot be judged from inside ivralo
an instance that answers a question	it is a pure reader; nobody can say what a server's tools do
a replay	a server is connected at the start of a run, before any recorded call

An instance opened for a side job carries only the servers its opener carries.

A broken entry fails the build

Listing is tolerant: ivralo mcp list shows the good entries and names each problem. Building the team is not. If mcp.json has any problem, the team build fails with the problem named, rather than starting specialists with fewer tools than you think they have. ivralo doctor names every problem without connecting.

At run time the servers connect at the start of each run. A server that fails to connect there is skipped with a log line, not an error. So test a new entry before relying on it:

ivralo mcp test everything

connects for real, lists the tools, and exits 1 with the reason when it cannot.

Adding a server

ivralo mcp add everything --command npx --arg -y --arg @modelcontextprotocol/server-everything --agent analyst
ivralo mcp add wiki --url https://wiki.example.com/mcp --header 'Authorization=Bearer ${WIKI_TOKEN}' --agent librarian

Option	Sets
`--command`, `--arg`	a local server; `--arg` is repeatable and kept unsplit
`--url`, `--transport`	a remote server
`--env KEY=VALUE`, `--header KEY=VALUE`	repeatable; `${VAR}` expands
`--agent`, `-a`	the preset that carries it; repeatable
`--timeout`	read timeout in seconds
`--include-tool`, `--exclude-tool`	repeatable
`--prefix`	the tool name prefix
`--disabled`	keep it in the file, attached to nobody
`--yes`	overwrite an existing entry without asking

ivralo mcp remove <name> deletes an entry, asking first unless --yes is given.

Recipes

The servers people ask for most are one command away:

ivralo mcp recipes
ivralo mcp add --recipe linear

Recipe	Gives	Needs	Carried by
`github`	issues, pull requests, files, code search, through the official Docker image	`GITHUB_PERSONAL_ACCESS_TOKEN`	`analyst`
`slack`	channels, messages, users	`SLACK_BOT_TOKEN`, `SLACK_TEAM_ID`	`analyst`
`notion`	pages and databases	`NOTION_TOKEN`	`librarian`
`atlassian`	Jira issues, Confluence pages	a browser sign-in on first use	`analyst`
`linear`	issues, projects, cycles	a browser sign-in on first use	`analyst`

A recipe writes every secret as a ${VAR} placeholder and prints the variables to set. The hosted servers go through mcp-remote, which signs in through the browser and keeps its token in its own store. --agent overrides the suggested preset. For plain GitHub work the built-in GitHub Clerk needs no Docker.

On Windows, servers started with npx need the cmd /c npx -y ... shape; the recipes write it that way for you, and paths in args are safest with forward slashes.