MCP Tools

MCP (Model Context Protocol) is the standard way for an agent to call out to an external tool: a database, a CRM, an observability stack, an internal API. The agent sees the tool as a structured function it can invoke, with typed inputs and outputs.

Nairi gives you two ways to wire up MCP servers:

• The MCP Marketplace for SaaS tools with OAuth. One click, no JSON.
• Custom MCP configs for anything else. Paste JSON, configure stdio or HTTP servers, pin credentials.

Both live at the org level. Once a server is configured, any agent in your org can attach it.

MCP Marketplace (Composio-powered)

The MCP Marketplace is powered by Composio, an integration platform that wraps hundreds of SaaS tools (Linear, Notion, GitHub, Slack, Stripe, Salesforce, Jira, Zendesk, and many more) behind a uniform OAuth flow.

Installing

1. Open Settings → MCP Marketplace.
2. Search or browse by category (Developer Tools, Databases, Communication, Project Management, Monitoring, Search, Utilities).
3. Click Install on the tool you want.
4. A dialog asks for an optional title and description. Click Install again.
5. An OAuth window pops up. Authorise the connection on the third-party's side. The dialog polls until the connection is confirmed.

The tool is now a regular MCP config at org level. Attach it to an agent from the Configuration tab.

Revoking

Open Settings → Integrations, find the Composio account, click Revoke. The connection is removed at the provider's side and the MCP config is deleted from your org.

You can also delete a single Composio-connected MCP config from Settings → Artifacts without revoking the whole Composio account.

Why use the Marketplace

A large catalogue of tools available out of the box. You don't have to write or maintain MCP configs yourself, learn the JSON schema, or figure out how to host each upstream server. Pick a tool, click connect, attach to an agent.

Custom MCP configs

For internal tools, anything the Marketplace doesn't cover, or anything that needs precise control over auth and transport.

Creating one

1. Open Settings → Artifacts.
2. Click New MCP Config. The form has three fields and a checkbox.
3. Title — short, descriptive. Shown in the agent editor.
4. Description — optional, what the config gives you.
5. Content (JSON) — the MCP server definition.
6. Mark as sensitive — if the config contains credentials inline, tick this. The content is hidden in the UI after saving, and changes require re-pasting the whole thing.
7. Save.

Two server types

stdio — local subprocess

The MCP server runs as a child process of the proxy. Use this for tools shipped as CLIs or npm packages.

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-linear"],
      "env": {
        "LINEAR_API_KEY": "lin_api_abc123..."
      }
    }
  }
}

HTTP or SSE — remote endpoint

The MCP server is reachable over HTTP. Use this for hosted MCP services or your own internal MCP endpoints.

{
  "mcpServers": {
    "internal-search": {
      "type": "http",
      "url": "https://mcp.internal.example.com/search",
      "headers": {
        "Authorization": "Bearer your-internal-token-here"
      }
    }
  }
}

Credentials in MCP configs

Inline credentials directly in the JSON. Vaults are for credentials the agent itself uses; MCP credentials are different — the MCP server runs inside the mcp-proxy sidecar, separate from the agent's container. The agent talks to the proxy over a local HTTP endpoint and never sees the proxy's configuration. The command, args, env, and headers stay on the proxy side, so the agent has no way to read them.

Two things to do when your MCP config contains credentials:

• Tick "Mark as sensitive" when creating the config. The dashboard hides the JSON content from casual viewing after save. To edit it later, click Replace content — you'll need to paste the whole config back in.
• Treat dashboard edit access like production access. Anyone who can edit an MCP config in your org can replace what it does.

How the mcp-proxy works

On managed runtimes, every customer container set runs an mcp-proxy sidecar alongside the agent. It's the piece that holds your MCP configs and runs the underlying MCP servers; the agent never touches them directly.

What the proxy does

1. Fetches MCP configs from the Nairi backend on startup. Only the configs attached to this agent are pulled, not the whole org library.
2. Starts the MCP servers defined in those configs. The behaviour depends on the server type:
   • stdio servers — the proxy spawns each as a subprocess and speaks JSON-RPC over the subprocess's stdin/stdout. If a subprocess crashes, the proxy auto-restarts it with exponential backoff (1s, 2s, 5s, 10s, 30s; up to 5 retries before giving up).
   • HTTP / SSE servers — no subprocess. The proxy forwards JSON-RPC requests to the remote URL and streams responses back.
3. Exposes a uniform HTTP endpoint to the agent. Every server, stdio or remote, is reachable at http://mcp-proxy.internal:8081/servers/<name>/mcp from inside the container.
4. Refreshes configs periodically. When you attach, detach, or edit MCP configs in the dashboard, the proxy picks up the new state without an agent redeploy.

What the agent sees

The agent's underlying CLI (Claude Code, Codex, OpenCode) is configured with an mcp.json that points at the proxy's HTTP endpoints — one entry per attached server. From the CLI's perspective, every MCP server is a local HTTP MCP. It calls the proxy, the proxy speaks whatever protocol the upstream actually wants, and the result comes back.

This is why MCP credentials don't need a vault: the agent's process only ever sees the proxy URL. The command, args, env, and headers from your MCP config live entirely on the proxy side. A compromised prompt or skill cannot inspect them.

What this is not

The mcp-proxy is not the secret proxy. Two different sidecars, two different jobs:

Attaching to an agent

Open the agent in Fleet, scroll to MCP Configs, tick the configs you want, click Save & Redeploy.

Each agent can attach multiple configs. The agent's mcp.json is rebuilt on every deploy from the configs it has attached.

When to use MCPs vs skills

The two overlap. The trade-off is control versus setup effort:

• MCP when you want functionality out of the box. Pick one from the Marketplace, click connect, done. No JSON to write, no maintenance. The catch: the agent gets whatever tool surface the upstream server exposes, with whatever output format it returns, and you can't trim or modify it.
• Skill when you want fine-grained control over what the agent can do — narrower tool surface, custom output format, your own auth/retry/error handling, exactly the context loaded into the agent's window. The catch: a skill is something you write and maintain. Schema changes, API deprecations, new endpoints — all on you.

In short: MCPs are easier to set up, skills give you more control.

The two compose. An agent can have the Linear MCP attached for general API access and a weekly-digest skill that uses the MCP plus your own template to produce the output you actually want.

See Skills as an alternative to MCPs for the full comparison.

Related

• Adding MCP tools to an agent
• Vaults · Security model
• API: MCP Configs

Can't find what you're looking for? Email support@nairi.ai.