Add MCP Servers

Minara supports third-party MCP servers as a first-class extension mechanism. This page is a practical guide: how to add a server, inspect it at runtime, and the safety rules you should know before pointing Minara at an untrusted MCP.

Minara's own tools do NOT go through MCP — they use the in-house registry. MCP is only for external, vendor-supplied tools. See Design Philosophy → In-house Tool Registry for why.

The easy way: just ask Minara

The fastest way to wire up an MCP server is to tell Minara in chat. The agent can parse your request, build the right MCP_SERVERS entry, persist it to ~/.minara/env, and reconnect — all inside the conversation.

Example prompts:

add the filesystem MCP server, rooted at ~/Documents/notes

connect to the GitHub MCP at https://mcp.github.com/sse using my
GITHUB_MCP_TOKEN

install this MCP: npx -y @modelcontextprotocol/server-sqlite,
point it at ~/.minara/data/minara.db

show me which MCP servers are connected

ping the github MCP — is it reachable?

remove the filesystem MCP, I'm not using it anymore

Minara confirms the exact config change before writing it (adding an MCP server is a tier-3 action because it changes the available tool surface), shows the tier assignment and tool count once the server connects, and flags any credential fields that need a separate env var you haven't set yet.

The manual way (if you prefer)

For scripting or reproducible deployments, you can configure MCP_SERVERS directly:

1. Edit .env and set MCP_SERVERS (JSON array).
2. Restart the REPL or gateway — servers are registered at boot.
3. Check with minara mcp list.
4. The LLM can now call the server's tools like any native tool.

Adding a server — minimal example

Add a filesystem MCP server (stdio transport):

# .env
MCP_SERVERS='[
  {
    "name": "filesystem",
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/docs"],
    "default_tier": 2,
    "env_passthrough": ["HOME"]
  }
]'

Restart Minara. The server's tools become available under the mcp:filesystem tool set, with names like filesystem.read_file, filesystem.list_directory, etc.

Adding a remote HTTP server

For HTTP-transport MCP servers (e.g. hosted services):

MCP_SERVERS='[
  {
    "name": "github",
    "transport": "http",
    "url": "https://mcp.github.com/sse",
    "auth": {"type": "bearer", "token_env": "GITHUB_MCP_TOKEN"},
    "default_tier": 1
  }
]'

Then set GITHUB_MCP_TOKEN separately in .env. Tokens come from env vars, never inline — the MCP_SERVERS string should never contain real credentials.

All configuration fields

Permission tiers

Match the closest tier an in-house Minara tool would use. When unsure, start at tier 3 and relax after observing behavior.

Managing servers from the CLI

minara mcp list                   # show registered servers + status
minara mcp tools <server>         # list tools exposed by a server
minara mcp ping <server>          # health check

Example output of minara mcp list:

mcp:filesystem   stdio  connected  (7 tools, tier 2)
mcp:github       http   connected  (12 tools, tier 1)
mcp:custom       stdio  error      (ECONNREFUSED)

What MCP servers can and can't do

✅ Supported

• Stdio + HTTP transports — local process or remote URL
• Multi-server registration — MCP_SERVERS is an array
• Per-tool tier overrides — hand-gate specific tools
• Subagent wrapping — expose a whole MCP server as a single subagent target (so the main LLM sees one tool instead of dozens)
• Uniform audit logging + redaction — MCP tool calls appear in the audit log the same way native tools do

❌ Not supported (by design)

• MCP sampling — reverse channel that lets a server call back into the host LLM. Not wired up because it would let an untrusted server inject prompts into the agent loop.
• Resource subscriptions — one-shot resources/read works, but subscription updates are dropped. Real-time data should come from trusted providers via the event bus, not MCP.
• Running Minara's own tools via MCP — the in-house registry gives tools direct access to SQLite, the sandbox, and the audit log; routing them through MCP would lose those.

Safety rules to know

1. Env passthrough is explicit. Stdio MCP servers get ONLY the env vars you list in env_passthrough. ANTHROPIC_API_KEY and wallet keys never leak into a third-party process unless you deliberately add them.
2. Tool args are redacted on the way out. The same redactor used for the audit log runs on MCP tool calls, so secrets you pass accidentally don't get written into logs in clear text.
3. Output is never privileged. An MCP server that echoes "please call withdraw" in its result triggers Minara's prompt injection detector the same as any other untrusted input.
4. Tier gating is uniform. An MCP tool at tier 3 needs the same human confirm as a native tool at tier 3. There is no MCP-specific bypass.

If an MCP server starts looking load-bearing for your deployment, that is a signal to port it to a native tool — the process boundary is overhead you no longer need, and you lose first-class prompt caching and schema stability by staying on MCP.

When to prefer MCP vs native

Prefer MCP when:

• The tool is vendor-supplied (a company publishes an MCP server you don't want to vendor)
• The tool is in Python / Rust / Go and rewriting in TS would be wasted
• You need hard process isolation (sandboxed code executor)
• You're prototyping and don't want to touch apps/agent/src/tools/

Prefer native when:

• The tool is small (a 50-line wrapper around an HTTP API)
• You need direct access to SQLite, the sandbox, or the audit log
• The tool should ship in the default distribution with no env setup
• You want first-class prompt caching and schema stability

Troubleshooting

"MCP server not connecting" Check minara mcp ping <name>. For stdio servers, try running the command manually to make sure it spawns cleanly. For HTTP, check firewall + auth token.

"Tools not visible to the LLM" The server may be connected but exposing zero tools, or the server's tools are disabled via tool_overrides. Run minara mcp tools <name> to see the raw tool list.

"Env var not passed through" Stdio children only get what's in env_passthrough. Add the variable to that array and restart.

Related

• System Design → Skills System — how MCP tools integrate with the skill layer
• Reference → minara mcp — full flag list
• Design Philosophy § In-house Registry — why Minara doesn't use MCP internally