MCP Servers

An MCP server is an external tool provider. Nakama acts as an MCP client: it connects to servers you register, caches their tools, and exposes them in chat like builtin tools.

• Register a server once (platform admin)
• Assign it to profiles that need it
• Tools appear at chat time, namespaced as {serverName}__{toolName}

Use MCP when you need product-specific or internal capabilities — databases, SaaS APIs, local binaries — without writing custom Nakama code. For capabilities every profile should have by default, use a builtin tool or bundled skill instead.

Transports

HTTP — Nakama opens a streamable HTTP connection and reuses it across turns.

{
  "url": "https://mcp.example.com/sse",
  "headers": { "Authorization": "Bearer my-token" }
}

stdio — Nakama spawns one process per profile, with cwd set to that profile's soul directory (~/.nakama/orgs/{orgId}/profiles/{profileId}/). HTTP servers share one connection across profiles.

{
  "command": "npx",
  "args": ["-y", "some-mcp-package"],
  "env": { "API_KEY": "secret-value" }
}

Tool naming and lifecycle

MCP tools are namespaced as {serverName}__{toolName} to avoid collisions with builtins and other servers (e.g. github__read_file). Invalid characters become _; duplicates get a numeric suffix.

Nakama caches the tool list at connect time — it is not re-fetched on every chat turn.

• Connect — opens the client, fetches and caches tools
• Sync — refreshes the cache from an existing connection (after the server adds/removes tools)
• Startup — Nakama auto-reconnects every enabled server; failures log a warning and set status to error

Setup

Platform admins manage servers at Agent → System → MCP and assign them on Agent → Profiles → profile → MCP servers. Registering a server does not assign it to any profile.

Add a server

1. Open Agent → System → MCP → Add server
2. Choose HTTP or Command, enter name and config
3. Test connection, then save — enabled servers connect immediately

Assign to a profile

1. Open the profile on Agent → Profiles
2. In MCP servers, click Add MCP server, then pick an existing server or create a new one
3. Unassigning removes tools from the next chat; deleting a server removes it from all profiles

Example: Exa web search

Nakama ships a preinstalled exa server (https://mcp.exa.ai/mcp) with web_search_exa and web_fetch_exa. The shared free tier can rate-limit; add your own Exa API key under Headers:

• Key: x-api-key
• Value: your API key

{
  "mcpServers": {
    "exa": {
      "url": "https://mcp.exa.ai/mcp",
      "headers": { "x-api-key": "YOUR_EXA_API_KEY" }
    }
  }
}

Tools appear as exa__web_search_exa and exa__web_fetch_exa.

Example: Firecrawl

Nakama ships a preinstalled firecrawl server (https://mcp.firecrawl.dev/v2/mcp) with no API key. Assign it on Agent → Profiles when a profile needs JS-rendered public pages.

Keyless tools appear as firecrawl__firecrawl_search, firecrawl__firecrawl_scrape, and firecrawl__firecrawl_parse. Use scrape for JS-heavy public pages. Search is extra surface next to Exa and builtin web_search. Hosted parse is not for files in the profile workspace — use extract_document_text.

Firecrawl Cloud fetches the URL. Unlike web_fetch, the page is processed off the Nakama host. Keyless usage shares a daily cap on the host's public IP across every assigned profile, including automations and Telegram / WhatsApp / Discord.

Keyless MCP does not include interact, crawl, or map. For login walls, forms, and clicks, use the agent-browser skill.

To raise limits or unlock crawl / interact / map, add a Firecrawl API key under Headers, then Reconnect or Sync tools:

• Key: Authorization
• Value: Bearer YOUR_FIRECRAWL_API_KEY

That header is shared by every profile assigned to this server. After sync, keyed tools are available on all of them until you unassign or rotate the header.

{
  "mcpServers": {
    "firecrawl": {
      "url": "https://mcp.firecrawl.dev/v2/mcp",
      "headers": { "Authorization": "Bearer YOUR_FIRECRAWL_API_KEY" }
    }
  }
}

Import from an existing config

Use Import JSON or paste a Cursor-style mcpServers block onto the form. A bare server object (top-level command or url) also works — the first entry fills the form for review.

Secrets

HTTP headers and stdio env values are secrets:

• API and dashboard return them as ••••••••
• Leave a field blank when editing to keep the stored value
• Test connection merges your input with stored secrets, so you can test without re-entering them

Config reference

HTTP

stdio

Permissions

MCP management is platform-admin only (same as profiles, builtins, and skills).

Troubleshooting

• error status — check lastError: wrong URL, missing command, unreachable host, or expired credentials
• No tools discovered — server connected but returned zero tools; fix server-side config, then Sync tools
• "not connected" on tool call — connection dropped; reconnect. For stdio, confirm the command is on PATH
• Exa rate limit — add an x-api-key header with your Exa API key, then reconnect
• Firecrawl rate limit — add an Authorization header with Bearer plus your Firecrawl API key, then reconnect. This also unlocks crawl / interact / map for every assigned profile
• Unexpected tool name — names are sanitized to a-zA-Z0-9_-; tools.list on server user.tolaria becomes user_tolaria__tools_list

Related

• Builtin tools — tools that ship with Nakama
• Agent browser — login walls and interactive pages
• Profiles — designing bots and tool access
• Multi-tenancy — org roles and admin boundaries