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.

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¶

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

One label per agent¶

A model provider rejects a request carrying two MCP entries with the same server_label, and it rejects the whole request — so an agent holding two capabilities with the same label could not answer anything at all, not even a greeting. This is easy to do by accident: two copies of the same capability whose configurations differ only in some detail you cannot see, such as a stray space in the URL.

PrimeThink now keeps the first entry for a given label and drops the later duplicates when it builds an agent's tool list, so the agent keeps working. Only one of the two configurations is in effect, though, and which one is not something you should rely on — if two capabilities share a label deliberately, give them distinct labels, and if one is a leftover, remove it from the agent.

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.

Running on Anthropic (Claude) models¶

The same MCP capability that runs on OpenAI also runs on direct Anthropic — PrimeThink translates the options into Anthropic's MCP-connector format at bind time (server_label → name, server_url → url, allowed_tools → tool_configuration.allowed_tools, and the Authorization Bearer token → authorization_token). Anthropic's connector is more restrictive than OpenAI's, so a capability must meet four conditions to attach on a Claude model:

1. require_approval must be an explicit "never". Anthropic has no tool-approval flow, so a server whose calls would be gated on OpenAI can't be attached safely. The integration is fail-closed: anything other than "never" — including omitting the field — skips the server on Anthropic, with a logged warning. (Setting "never" is also the only mode in which OpenAI runs the tools without pausing for approval.)
2. server_url and server_label must both be set. Anthropic rejects an entry missing either one with an error that would fail every message, so incomplete configs are skipped instead of attached.
3. Auth must be a Bearer token in the Authorization header. Anthropic accepts a single OAuth bearer token — nothing else. The Bearer prefix is stripped automatically (a schemeless raw token also works). All other headers are dropped, with a logged warning naming them; a server that requires a custom header (e.g. X-Api-Key) will authenticate on OpenAI but not on Anthropic. Non-Bearer schemes such as Basic are not supported.
4. allowed_tools, if set, must be interpretable as a list of tool names. A bare string and the flat-editor {"0": ..., "1": ...} shape are normalized automatically; a value that can't be interpreted skips the server rather than silently widening the restriction.

A skipped server never breaks the agent — the rest of its tools keep working; the agent just runs without that MCP server. If MCP tools seem to disappear after switching an agent to a Claude model, check the server logs for skipped on Anthropic warnings, which state the exact reason and fix.

Only URL-based (Streamable HTTP) MCP servers are supported on Anthropic — which is the only kind PrimeThink connects to anyway.

When a tool fails¶

When a hosted-MCP interaction fails, the provider (OpenAI or Anthropic alike) 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 and direct Anthropic models only — hosted MCP is skipped, with a logged warning, on AWS Bedrock and every other unsupported provider.
• On Anthropic, require_approval: "never" is mandatory (fail-closed) and only a Bearer Authorization header is sent — custom headers are dropped.
• No stray whitespace in server_url.
• Secrets → ${SETTING_NAME} placeholders in headers, defined in settings first.

Related Topics¶

• Capabilities — what capabilities are and how they're used
• API Capabilities — wrap a single HTTP endpoint instead
• Supported LLMs — which providers and models your agent can use
• Working with AI Agents — assigning capabilities to an agent