MCP Tools
Plug external tools into your agents using the Model Context Protocol. Install MCP servers from the Marketplace or paste a custom JSON 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)
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
- Open Settings → MCP Marketplace.
- Search or browse by category (Developer Tools, Databases, Communication, Project Management, Monitoring, Search, Utilities).
- Click Install on the tool you want.
- A dialog asks for an optional title and description. Click Install again.
- 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
- Open Settings → Artifacts.
- Click New MCP Config. The form has three fields and a checkbox.
- Title - short, descriptive. Shown in the agent editor.
- Description - optional, what the config gives you.
- Content (JSON) - the MCP server definition.
- 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.
- Save.
Two server types
stdio - local subprocess
The MCP server runs as a subprocess of the agent's CLI, inside the agent's sandbox. 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. The agent reaches it through the Nairi agent MCP gateway.
{
"mcpServers": {
"internal-search": {
"type": "http",
"url": "https://mcp.internal.example.com/search",
"headers": {
"Authorization": "Bearer your-internal-token-here"
}
}
}
}Credentials in MCP configs
Where an MCP credential ends up depends on the server type:
- Remote (
url) servers and Marketplace tools - the agent reaches them through the Nairi agent MCP gateway, which adds the config'sheaders(or the Composio key) on its side. These credentials stay out of the agent's sandbox. Inline them directly inheaders. Self-hosted agents neednairid0.0.129 or later for this; releases before 0.0.128 don't use the gateway and download the full configs,headersand the Composio key included. stdioservers - the agent's CLI starts them inside the sandbox, so theircommand,args, andenvare in the CLI's config, where the agent can read them, credentials included. To keep a credential out of the agent's reach, use a remote MCP server.
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 agent MCP gateway works
Every agent's CLI config has one MCP server named nairi, pointing at Nairi's agent MCP gateway, plus the agent's stdio servers as they are.
- The gateway serves remote and Marketplace MCPs. It loads the MCP configs attached to this agent, connects to each remote server with that config's headers (or to Composio's hosted MCP with the Composio key), and merges their tools, resources, and prompts into one server.
stdioservers run in the sandbox. The agent's CLI starts them itself, like any local MCP server.- Each agent has its own MCP key. The
nairientry authenticates with a per-agent key that works only on the gateway endpoint (/api/agents/mcp), only over HTTPS, and only for its own agent. On managed runtimes the agent only sees a placeholder; the secret proxy fills in the real key on requests to the gateway. - The gateway speaks streamable HTTP only. It doesn't serve servers with
"type": "sse". Managed agents leave them out; self-hosted agents run them locally.
If a managed agent can't reach the gateway, it starts with its stdio servers only and tries the gateway again every 5 minutes. Self-hosted agents need nairid 0.0.129 or later.
What the agent sees
Tools from remote and Marketplace MCPs appear under the nairi server, prefixed with the server's name from your config and __: a create_issue tool from a server named github shows up as github__create_issue, and Gmail's send_email from the Marketplace as composio_gmail__send_email. In Claude Code, mcp__github__create_issue becomes mcp__nairi__github__create_issue.
If your rules, skills, or prompts name MCP tools by their old names, update them to the prefixed names.
In the prefix, characters other than letters, digits, -, and _ become _, and a server name used twice gets -2, -3. A local server of your own named nairi is renamed nairi-2.
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
Can't find what you're looking for? Email support@nairi.ai.
Skills
Reusable capability packages that extend what your agents can do. Install skills from the Nairi Marketplace or package and upload your own custom ones.
Vaults & Secrets
Org-level encrypted key-value storage for credentials, with safe runtime injection into your agents. Domain-pin secrets so they only leak where intended.