# MCP Tools

Plug external tools into your agents. Install from the Marketplace or paste a custom config.





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) [#mcp-marketplace-composio-powered]

The [MCP Marketplace](https://app.nairi.ai/settings/mcp-marketplace) is powered by [Composio](https://composio.dev), 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 [#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 [#revoking]

Open [Settings → Integrations](https://app.nairi.ai/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](https://app.nairi.ai/settings/artifacts?tab=mcp-configs) without revoking the whole Composio account.

### Why use the Marketplace [#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 [#custom-mcp-configs]

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

### Creating one [#creating-one]

1. Open [Settings → Artifacts](https://app.nairi.ai/settings/artifacts?tab=mcp-configs).
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 [#two-server-types]

#### `stdio` — local subprocess [#stdio--local-subprocess]

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

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

#### `HTTP` or `SSE` — remote endpoint [#http-or-sse--remote-endpoint]

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

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

### Credentials in MCP configs [#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.

<Callout type="info">
  On self-hosted runtimes there's no mcp-proxy. MCP configs from the dashboard are written to local files (`~/.claude/mcp.json` etc.) that the underlying CLI reads directly. Any credentials in the JSON live on the agent's filesystem — assess whether that's acceptable for your setup.
</Callout>

## How the mcp-proxy works [#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 [#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 [#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* [#what-this-is-not]

The mcp-proxy is not the [secret proxy](/help/vaults/security-model). Two different sidecars, two different jobs:

| Sidecar          | Sits between agent and... | Handles                                                     |
| ---------------- | ------------------------- | ----------------------------------------------------------- |
| **secret proxy** | the public internet       | vault secret injection on outbound HTTPS to allowed domains |
| **mcp-proxy**    | MCP servers               | tool calls; isolates MCP configs from the agent             |

## Attaching to an agent [#attaching-to-an-agent]

Open the agent in [Fleet](https://app.nairi.ai/agents/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 [#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](/help/skills)** 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](/help/skills#skills-as-an-alternative-to-mcps) for the full comparison.

## Related [#related]

* [Adding MCP tools to an agent](/help/building-agents/how-to-deploy#mcp-configs)
* [Vaults](/help/vaults) · [Security model](/help/vaults/security-model)
* [API: MCP Configs](/api/mcp-configs/overview)

***

*Can't find what you're looking for? Email [support@nairi.ai](mailto:support@nairi.ai).*