Skip to content

MCP Capabilities

An MCP capability (type: "mcp") connects your agent to a remote, already-deployed Model Context Protocol server. The server's tools become available to the model — so a single capability can add a whole suite of related tools at once.

Like API capabilities, MCP capabilities are pure configuration: no code, just a small options blob pointing at the server. They're the best choice for plugging in rich, multi-tool integrations that are built and maintained outside PrimeThink.

For the bigger picture of how capabilities fit together, see Capabilities.

MCP requires an OpenAI model

Hosted MCP is implemented through OpenAI's Responses API. As a result:

  • If the agent's active model is an OpenAI model, MCP tools are attached.
  • If the active model is anything else (Anthropic, Gemini, Groq, DeepSeek, Mistral, …), MCP capabilities are skipped and a warning is logged — the rest of the agent is unaffected.

Make sure your agent uses an OpenAI model before relying on an MCP capability.

Options schema

A minimal MCP capability against a public server with no auth:

{
  "server_label": "deepwiki",
  "server_url": "https://mcp.deepwiki.com/mcp",
  "require_approval": "never"
}

With auth headers (the token comes from settings, not hard-coded):

{
  "server_label": "ha-remote",
  "server_url": "https://your-instance.ui.nabu.casa/api/mcp",
  "require_approval": "never",
  "headers": {
    "Authorization": "Bearer ${HA_REMOTE_TOKEN}"
  }
}

Field reference

Key Required Description
server_label Yes Short identifier for the server, shown in errors and traces. Whitespace stripped.
server_url Yes The MCP server endpoint. Supports ${SETTING} placeholders. Whitespace stripped — see the warning below.
require_approval No "never" to auto-approve tool calls, or an OpenAI approval-policy object. Whitespace stripped.
headers No Auth or other headers. Values support ${SETTING} placeholders (e.g. Authorization).
extra keys No Any additional keys (such as allowed_tools or tool_filter) are passed through to the MCP tool config. String/dict values still get placeholder resolution.

The built config always includes "type": "mcp".

Avoid stray whitespace in server_url

A leading or trailing space in server_url causes OpenAI's MCP connector to fail with HTTP 424 ("failed to retrieve tool list"), which previously surfaced to users as an empty or blank response. PrimeThink now trims server_url (and server_label/require_approval) automatically, but it's still good practice to keep the value clean.

Settings placeholders (${SETTING_NAME})

Never hard-code tokens. Any string value in options can contain ${SETTING_NAME} placeholders, resolved at runtime from your user/group settings.

  • The name must be word characters (letters, digits, underscore).
  • Example: "Authorization": "Bearer ${HA_REMOTE_TOKEN}".
  • Placeholders are resolved in server_label, server_url, require_approval, headers, and any extra string/dict values.
  • If a referenced setting is missing or empty, the MCP config is skipped and the issue is logged. Define the setting before enabling the capability.

You configure settings on the Settings page (or via the admin API):

Setting name:  HA_REMOTE_TOKEN
Setting value: eyJhbGci...

The value is then available as ${HA_REMOTE_TOKEN} in the capability's options. See API Capabilities → Dot-notation keys for expressing nested options in a flat editor — the same expansion applies here.

When a tool fails

When a hosted-MCP interaction fails, OpenAI returns the failure as a content block with an error rather than throwing. PrimeThink detects these and surfaces them to you in the chat as:

⚠️ A connected tool failed: MCP server '{label}', tool '{name}': {error}

and logs the error server-side. Successful MCP interactions produce no such message. (This replaces the older behavior where a failing MCP server could surface as a silent, empty response.)

Examples

Both examples use real, live MCP servers.

Public, no auth — DeepWiki

When you'd use this: let an agent answer questions about any public GitHub repository's documentation. DeepWiki is open, so no token is needed.

{
  "name": "DeepWiki",
  "type": "mcp",
  "options": {
    "server_label": "deepwiki",
    "server_url": "https://mcp.deepwiki.com/mcp",
    "require_approval": "never"
  }
}

This gives the agent DeepWiki's tools (for example, an ask_question tool) to query repository documentation.

Authenticated — GitHub's remote MCP server

When you'd use this: give an engineering or project-tracking agent live access to your GitHub — issues, pull requests, code search, and more — through GitHub's officially hosted MCP server. Authentication is a personal access token passed as a Bearer header, stored as a setting so it never appears in the config.

{
  "name": "GitHub",
  "type": "mcp",
  "options": {
    "server_label": "github",
    "server_url": "https://api.githubcopilot.com/mcp/",
    "require_approval": "never",
    "headers": {
      "Authorization": "Bearer ${GITHUB_MCP_PAT}"
    }
  }
}

Define a setting named GITHUB_MCP_PAT holding your token before enabling the capability. Scope the token to the minimum your agent needs — a compromised token grants whatever access it carries.

Quick reference

Minimal MCP capability:

{ "server_label": "label", "server_url": "https://host/mcp", "require_approval": "never" }

Rules to remember:

  • OpenAI models only — MCP capabilities are skipped on other providers.
  • No stray whitespace in server_url.
  • Secrets → ${SETTING_NAME} placeholders in headers, defined in settings first.