# Plugin integration requests

Source: https://codeherder.com/docs/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](https://codeherder.com/docs/integrations/#agent-access). A workspace admin then decides.

This guide is for plugin authors. Admins find the request screens in [Plugin sources](https://codeherder.com/docs/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](https://codeherder.com/docs/integrations/#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](https://codeherder.com/docs/integrations/#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.

## Related guides

- [Plugin sources](https://codeherder.com/docs/plugin-sources/) — add, pin and remove a plugin source, and decide requests.
- [Agent access](https://codeherder.com/docs/integrations/#agent-access) — turn an integration on and use its tools.
- [Skills](https://codeherder.com/docs/skills/) — the catalog that a plugin source fills.
