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
envvalue 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_KEYshould declaredatadoginstead. - A kind outside the catalog.
- A destructive tool.
- An automatic enable. Only an admin turns an integration on.
Related guides
- 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