Give each Claude Code subagent
only the MCP tools it needs.

What Claude Code gives you

Claude Code subagents can be limited in their own definition file (subagents documentation, read 2026-10-22):

• tools and disallowedTools can allow or withhold a whole MCP server, for example mcp__github__*.
• mcpServers can declare servers that only that subagent sees. An inline entry uses the same schema as .mcp.json, and HTTP servers are supported.

That is a client-side choice made by name. It does not know whether a tool reads or writes, and a server the subagent can reach still acts with that server’s own credentials.

What MCPProxy adds

MCPProxy checks every call on the proxy side, so the limit holds however the agent got there:

• Servers. The agent only reaches the servers in its profile.
• Tool type. A profile can set max_tier to read, write or destructive. Tiers come from each tool’s own MCP annotations (readOnlyHint, destructiveHint). With a read cap, write and destructive tools are hidden and refused, unless a tools.allow rule admits one on purpose.
• Allow and deny rules. tools.allow and tools.deny match server:tool patterns. Deny wins.
• Unlabelled tools. A tool with no annotations is not guessed at. With max_tier set to read or write, it is hidden by default. You can classify it, allow it, or change the profile’s unannotated setting.
• A token that cannot switch. A token pinned to a profile cannot switch to another one, whatever URL it uses.

Set it up

1. Require credentials. By default MCPProxy lets a caller with no token connect with full access, so a token alone limits nothing. Start it with mcpproxy serve --require-mcp-auth (or set "require_mcp_auth": true in the config) before you rely on scoped tokens.

2. Create a read-only profile with the servers the reviewer needs:

   mcpproxy profile create reviewer-readonly --servers github,notion --max-tier read

3. Mint a token pinned to it:

   mcpproxy token create --name pr-reviewer --profile reviewer-readonly

   The token is shown once. Save it somewhere safe and keep it out of Git.

4. Give only that subagent the token. In .claude/agents/pr-reviewer.md, define MCPProxy inline so the main conversation does not get it, and allow-list the tools the reviewer may use. Without tools, a subagent inherits the main conversation’s other tools, including any broader MCP connection:

   ---
   name: pr-reviewer
   description: Reviews pull requests. Read-only GitHub and Notion access.
   tools: Read, Grep, Glob, mcp__mcpproxy-reviewer__*
   mcpServers:
     - mcpproxy-reviewer:
         type: http
         url: http://localhost:8080/mcp
         headers:
           X-API-Key: <the pr-reviewer token>
   ---
   
   Review the pull request. Use MCPProxy's retrieve_tools to find the tools you need.

   Claude Code only loads inline servers from a project’s .claude/agents/ after you trust the folder, and the token sits in that file, so keep the file out of version control or use your own ~/.claude/agents/ folder.

5. Check what the agent can reach before you rely on it:

   mcpproxy profile show reviewer-readonly --effective
   mcpproxy access explain --tool github:create_issue --token pr-reviewer

   The second command walks the checks one call would meet and says which one blocks it and how to change that.

   When the agent tries a tool outside its profile, the proxy refuses before anything reaches the upstream server and says why, for example that the tool is a write tool and the profile allows read tools only.

Heads up

• The main session. If your main Claude Code session is connected to MCPProxy with a wider credential, give it its own profile too. mcpproxy connect claude-code --profile work binds that client to a profile.
• Profiles are not a promise about what a tool does. Tiers come from what each server declares, and a tool with no annotations counts as read when a profile has no cap. A server that mislabels a destructive tool as read-only is trusted at its word. Review a server’s tools before you trust it, and see how changes are held for review.
• Admin actions stay with you. Agent tokens can find and call tools within scope. They cannot add or change servers.
• max_tier needs MCPProxy v0.70.0 or later.

Links

• Profiles (docs)
• Agent tokens (docs)
• Agent instructions (docs)
• Claude Code setup guide