CodeHerderSearch⌘KRequest access →

Plugin integration requests

Let a Claude Code plugin ask for agent access to an integration with integrations.yaml, and see how an admin decides, what the sync refuses and the tool names.

A plugin can need a vendor service such as Jira or Datadog. It cannot carry the credential, and CodeHerder never runs the plugin’s own server. Instead, the plugin requests a vendor integration. A workspace admin then decides.

This guide is for plugin authors. Admins find the request screens in Plugin sources.

What a request is

A plugin source sync reads two inputs. The first is an optional integrations.yaml file. The second is each MCP server that the plugin declares. For each need, the sync records one request for one integration kind.

  • A request is a note for the admin. It turns nothing on.
  • The sync never runs the plugin’s server.
  • The sync stores the server name and the match evidence only. It never stores a command, an argument, a URL path or query, an env value or a header.
  • An admin turns on agent access with the integration’s own control. Until then, no session gets it.

The integrations.yaml file

Put the file at integrations.yaml in the plugin root. No other name works, and no manifest key points to it.

integrations:
  - kind: jira
    tools: [jira_search, jira_get_issue]
    purpose: Read the Jira issue a task came from.
Key Needed Meaning
kind Yes The integration kind, for example jira. A stable key.
tools No The tools the plugin wants. Leave it out to ask for the kind only.
purpose No One line of plain text for the admin.

The decode is strict. These bounds apply:

Bound Value
File size 16 KiB
Entries 16
Tools per entry 32
purpose 280 bytes, one line, no control characters

A duplicate kind, a duplicate tool, an empty file, a second YAML document, an unknown key at any level or a value of the wrong type refuses the whole file. The reason is integrations_manifest_invalid. The detail names the line and the key, never a value. Keys such as url, command, env, headers and token are unknown keys, so they refuse the file.

An example plugin

jira-kit/
  .claude-plugin/plugin.json
  .mcp.json
  integrations.yaml
  skills/triage/SKILL.md

.mcp.json declares the Jira server for installs that load it natively:

{
  "mcpServers": {
    "atlassian": { "type": "http", "url": "https://mcp.atlassian.com/v1/sse" }
  }
}

integrations.yaml names jira with the tools jira_search and jira_get_issue. The skill skills/triage/SKILL.md calls mcp__jira__jira_search. Keep .mcp.json for those other installs. In a CodeHerder session the plugin’s own server stays off.

How a server matches an integration

CodeHerder matches a declared server to a kind by evidence in the server entry. The server name never matches.

Kind URL host Package
jira mcp.atlassian.com None
github api.githubcopilot.com @modelcontextprotocol/server-github, github-mcp-server, ghcr.io/github/github-mcp-server
gitlab None @modelcontextprotocol/server-gitlab
datadog None None
  • A host matches when it is equal, or when it is a subdomain on a dot boundary.
  • A package matches the command or an argument. CodeHerder strips an npm @version, an image tag and a digest first.
  • A stdio argument that is a URL matches by host. This covers mcp-remote <url>.
  • A server that matches no kind is refused with mcp_server_no_integration.

Tool names

Claude sees an integration tool as mcp__<kind>__<tool>. For Jira, mcp__jira__jira_search is the search tool. CodeHerder names one server for each kind by the bare kind.

Tool Class
jira_search Read
jira_get_issue Read
jira_get_transitions Read
jira_add_comment Write
jira_transition_issue Write
jira_create_issue Write
jira_get_create_fields Read
jira_get_link_types Read
jira_link_issues Write
jira_get_edit_fields Read
jira_update_issue Write

A write tool asks for approval on each call. Agent access explains the flow. A tool that is not in the list is destructive and stays off.

The CLI path for Datadog

Datadog has no MCP path. Request it with the kind only:

integrations:
  - kind: datadog
    purpose: Search logs during triage.

Do not list tools. Once an admin enables Datadog, the stage runs pup directly. The key in the session is a placeholder, and the server relay adds the real credential. pup auth login is refused. See Agent access.

Reading the sync report

Reason What it means and what to do
mcp_server_integration_requested A server matched a kind. The sync recorded a request. An admin decides.
mcp_server_no_integration No kind matches the server. Name a kind in integrations.yaml if one fits.
mcp_servers_unsupported CodeHerder could not read a server source. Fix the JSON.
integrations_manifest_invalid The strict decode refused integrations.yaml. Fix the line in the detail.
integration_kind_unknown The kind is not in the catalog.
integration_tool_unknown The kind has no such tool, or the kind has a CLI path and no tools.
integration_tool_off The tool is destructive and stays off.

A refused entry does not stop the other items. They still import.

What stays refused

  • The plugin’s own MCP server. It never runs and never persists.
  • Hooks and LSP servers.
  • Environment variables. A plugin that needs DD_API_KEY should declare datadog instead.
  • A kind outside the catalog.
  • A destructive tool.
  • An automatic enable. Only an admin turns an integration on.
  • Plugin sources — add, pin and remove a plugin source, and decide requests.
  • Agent access — turn an integration on and use its tools.
  • Skills — the catalog that a plugin source fills.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close