Custom Plugins

Plugins differ in how they reach their backend, and each plugin’s own file (../plugins/<name>.md) is the source of truth for its routing. The categories are:

• CLI-only plugins require a harness with shell or terminal access — do not route them through web_request, do not use a user-paste fallback, and do not recommend a separate protocol MCP to work around the lack of a shell. If there is no shell, tell the user the plugin requires CLI access and stop.
• Hybrid plugins support more than one path: use the CLI (or a protocol MCP) when shell access exists; otherwise call the plugin’s HTTP host through web_request when that host is allowlisted. Follow the routing in the plugin’s file.
• Some hybrid plugins split by operation: their view-only / read hosts are allowlisted for web_request and work on every surface, while their write or tx-builder hosts require a CLI harness. On chat-only surfaces, do not retry a write host through web_request and do not fall back to user-paste — follow the plugin file, which typically links the user to the protocol’s web UI instead.

Custom or user-supplied plugins are almost certainly not in the allowlist and will be rejected by web_request.

Priority order for HTTP calls

Use this order for every HTTP-based plugin call — native or not. CLI-only plugins follow their plugin file and require shell access. Hybrid plugins follow the CLI/HTTP routing in their own plugin file.

1. Harness HTTP tool (preferred whenever available)

If the current environment lets you call HTTP APIs directly — e.g. Claude Code, Codex, Cursor, or any harness where you have a fetch / curl / shell tool — use that tool first for HTTP-based plugins, even for native plugins. It supports any HTTP method (GET, POST, etc.), avoids the allowlist entirely, and gives you the full response without round-tripping through the MCP.

Only fall back to web_request if you don’t have a usable HTTP tool in the current harness.

2. web_request (when no harness HTTP tool exists)

If the harness has no direct HTTP capability, first check whether the plugin is CLI-only. If it is, stop and tell the user it requires a CLI harness. Otherwise, route the call through Base MCP’s web_request:

• Native HTTP plugin host — works if the host is allowlisted.
• Non-native plugin host — will be rejected. Do not silently retry. Move to path 3.

3. User-paste fallback (Claude / ChatGPT consumer surfaces, non-native hosts)

Claude and ChatGPT can fetch GET URLs themselves, but for security reasons they will only fetch URLs that the user has pasted into the chat. The agent cannot freely construct and fetch arbitrary URLs on its own.

That makes the fallback effectively GET-only: there’s no equivalent escape hatch for POST/PUT/DELETE with custom headers and a body, because the user can’t realistically inject those into the chat in a fetchable form.

So for non-native plugins on Claude / ChatGPT consumer surfaces:

• Only GET-style APIs are viable. If the protocol’s API requires POST or other write methods to retrieve calldata, surface this limitation to the user — explain that their environment can’t perform the fetch and that they would need a harness with HTTP tools (e.g. Claude Code) to proceed.
• For GET endpoints:
  1. Construct the full URL with every query parameter encoded inline (address, amount, slippage, chain, etc.).
  2. Show the URL to the user and ask them to paste it back into the chat. Once pasted, you can fetch it yourself — that’s the security model these surfaces enforce.
  3. Parse the response and continue the flow (e.g. map returned calldata into the batched-calls tool, then walk through the approval flow — see approval-mode.md and batch-calls.md).

Decision summary