Claude Sonnet 5 MCP Server Guide: Hidden Permission Changes

Abstract

After upgrading internal Claude Code deployments from claude-opus-4.8 to claude-sonnet-5, the MCP Server can be deployed successfully within minutes.

However, a critical silent failure was observed: subagents could no longer execute tool calls, with no logs or runtime errors.

After extensive debugging, three undocumented breaking changes in the subagent permission schema were identified. These changes are not reflected in official documentation as of July 2026.

This paper summarizes:

• Full MCP Server deployment workflow
• Key differences between Opus 4.8 and Sonnet 5
• Production-grade configuration templates
• Common runtime issues and fixes
• Cost and migration considerations

1. End-to-End Deployment Overview

A working Claude Code MCP Server requires six steps:

1. Install Claude Code CLI
2. Configure API authentication
3. Register MCP Server via claude_desktop_config.json
4. Configure subagent permissions (critical change in Sonnet 5)
5. Validate tools using MCP Inspector
6. Run end-to-end integration tests

1.1 Deployment Flow

The deployment process is strictly sequential:

• CLI installation → required before any configuration
• API key setup → required before server registration
• MCP JSON config → required before subagent permission setup
• Permission layer → critical difference between models
• Inspector validation → final safety check

Any misconfiguration in the permission layer leads to silent subagent failure with no logs, making validation essential.

2. Key Subagent Permission Differences (Opus 4.8 vs Sonnet 5)

2.1 tool_call_budget (Critical Change)

Sonnet 5 introduces a hard limit on tool usage per subagent session.

• If omitted → interpreted as 0
• Result → all tool calls are disabled
• No error logs are generated

Recommended values:

• Light tasks: 20
• Complex workflows: 80+

This is the most common migration failure point.

2.2 Permission Model Change

Opus 4.8 (Allowlist model)

You explicitly define allowed tools.

Sonnet 5 (Blocklist model)

• Use "*" to enable all tools
• Use denied_tools to restrict access

If legacy allowlist configs are reused, the system may return:

• Empty tool set
• Subagent executes nothing

2.3 max_turns Behavior Change

The iteration limit has changed silently:

• Old default: 25
• New default: 10 (not documented)

This causes:

• Early termination of multi-step tasks
• Incomplete workflows
• No visible warning logs

Recommended explicit configuration is required in production.

3. MCP Deployment Implementation

Step 1: Install CLI

npm install -g @anthropic-ai/claude-code
claude --version

If ENOENT occurs, PATH is not configured correctly.

Step 2: API Authentication

Direct API mode

export ANTHROPIC_API_KEY=sk-ant-xxxxx
claude mcp serve

Gateway mode (4sapi / OpenRouter)

Used for unified multi-model routing and cost tracking.

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY
});

Note: claude-sonnet-5 (marketing name) is different from API ID claude-sonnet-4-5.

Step 3: MCP Server Registration

{
  "mcpServers": {
    "claude-code": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/claude-code", "mcp", "serve"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-xxxxx"
      }
    }
  }
}

Important:

• The -y flag prevents interactive prompts
• Without it, MCP JSON stream breaks

Step 4: Subagent Permission Config

❌ Opus 4.8 (not compatible with Sonnet 5)

{
  "subagents": {
    "allowed_tools": ["read_file", "write_file"],
    "max_turns": 25
  }
}

✅ Sonnet 5 (correct configuration)

{
  "subagents": {
    "tool_call_budget": 40,
    "allowed_tools": "*",
    "denied_tools": ["execute_command"],
    "max_turns": 20
  }
}

Key point:

• Always explicitly define tool_call_budget
• Never reuse allowlist-only logic

Step 5: MCP Inspector Validation

npx @modelcontextprotocol/inspector \
npx -y @anthropic-ai/claude-code mcp serve

Expected result:

• Tools like read_file, write_file appear
• Missing tools indicate permission misconfiguration

4. Recommended Configurations by Scenario

5. Cost Comparison

Sonnet 5 reduces cost by ~80%.

Using an API gateway further improves:

• centralized billing
• multi-model routing
• unified logging

6. Common Runtime Issues

Issue 1: Authentication Failure

Cause:

• Environment variable not loaded in GUI context

Fix:

• Define API key inside MCP config env block

Issue 2: Invalid JSON Response

Cause:

• Missing -y flag in npx command

Fix:

• Always use npx -y in MCP server startup

Issue 3: Tool Calls Stop Early

Cause:

• tool_call_budget too low

Fix:

• Set minimum value ≥ 20

7. Frequently Asked Questions

Q1: Which API model ID should be used?

Use: claude-sonnet-4-5 Not: claude-sonnet-5

Q2: What does tool_call_budget control?

It defines the total number of tool calls allowed per subagent session.

Q3: Do config changes require restart?

Yes. Fully restart Claude Desktop.

Q4: Is MCP compatible with Cline / Cherry Studio?

Yes, but minor schema differences may exist. Use MCP Inspector for validation.

8. Conclusion

The main deployment risk in migrating to claude-sonnet-5 MCP Server comes from three undocumented changes:

• Mandatory tool_call_budget
• Shift from allowlist → blocklist permission model
• Reduced default max_turns

These changes introduce silent failure modes without logs, making debugging difficult.

For production systems:

• Always define all subagent parameters explicitly
• Avoid relying on defaults
• Use gateway routing for multi-model management
• Validate with MCP Inspector before deployment

Sonnet 5 significantly reduces cost, but requires stricter configuration discipline compared to Opus 4.8.