MCP Server Optimization Guide

Strategic guide for managing MCP servers in OpenCode to optimize context usage and performance.

Architecture Overview

Two-tier MCP system:

Current MCP Servers

Docker MCP (Official)

Custom MCP (Personal)

theslyprofessor Server Deep Dive

Tool Categories (23 total):

1. Routing (2): route_context, list_projects
2. Vault Management (2): create_article, generate_frontmatter
3. Outlook (2): get_flagged_emails, email_to_article
4. Context (3): morning_review, hil_status, daily_tasks
5. Vault Search (2): search_vault, get_article
6. ARF Framework (5): find_context, refresh_arf_catalog, get_context_stats, get_context_tree, get_context_path
7. Chezmoi (3): chezmoi_edit_config, chezmoi_search_configs, chezmoi_preview_diff
8. Server Management (1): restart_mcp_server

Performance Features:

• Parallel execution in morning_review (HIL + emails + tasks)
• Smart caching for ARF routing (5-min cache, checksum validation)
• Performance logging to /tmp/theslyprofessor-perf.log

Optimization Strategy

Always Enable (Core Functionality)

json
{
  "opencode-sessions": { "enabled": true },
  "registry": { "enabled": true },
  "theslyprofessor": { "enabled": true },
  "MCP_DOCKER": { "enabled": true }
}

Rationale:

• opencode-sessions → Session continuity across chats
• registry → Persistent task management (Convex-backed)
• theslyprofessor → 23 productivity tools (vault, email, ARF, chezmoi)
• MCP_DOCKER → Enables Brave search and Obsidian integration

Situational Enable

Always Disable

json
{
  "google-drive": { "enabled": false }
}

Reason: Requires OAuth setup, not yet configured

Context Budget Management

Token cost by server:

Model-specific recommendations:

Brave Search Rate Limits

CRITICAL: Brave Free AI plan = 1 req/sec, 2000/month

Best practices:

• NEVER call brave_web_search in parallel
• Wait 2+ seconds between searches
• Batch queries in separate messages
• Monitor quota with usage tracking

Example (correct):

bash
# Sequential with delays
brave_web_search "query 1"
sleep 2
brave_web_search "query 2"

MCP_DOCKER Integration

How it works:

1. OpenCode starts docker mcp gateway run automatically
2. Gateway connects to Docker MCP servers
3. Tools become available in OpenCode session
4. Gateway must remain running (OpenCode manages this)

Troubleshooting:

bash
# Check gateway status
ps aux | grep "docker mcp gateway"

# View gateway logs
tail -f /tmp/docker-mcp-gateway.log

# Verify servers enabled
docker mcp server list

When to Enable/Disable Servers

Session Start Checklist

Ask yourself:

1. Am I working in the vault? → Enable Obsidian
2. Do I need to research? → Enable Brave Search
3. Am I processing emails? → Enable outlook-sqlite
4. Multi-pane terminal work? → Enable zellij
5. Deploying to VPS? → Enable Hostinger (temporarily)

Mid-Session Changes

Enable server:

1. Edit ~/.config/opencode/opencode.json
2. Set "enabled": true
3. Reload OpenCode (Ctrl+R or restart)

Disable server:

1. Set "enabled": false
2. Reload OpenCode

Performance Monitoring

Check theslyprofessor performance:

bash
tail -f /tmp/theslyprofessor-perf.log

Metrics to watch:

• morning_review: <200ms typical
• search_vault: <100ms for 10 results
• find_context (ARF): <50ms with cache

Slow operations (expected):

• refresh_arf_catalog: 500-1000ms (scans all AGENTS.md files)
• get_flagged_emails: 200-400ms (SQLite query)

Configuration File Reference

Location: ~/.config/opencode/opencode.json

Template for custom server:

json
{
  "mcp": {
    "my-server": {
      "type": "local",
      "command": ["bun", "/path/to/index.ts"],
      "environment": {
        "API_KEY": "{env:MY_API_KEY}"
      },
      "enabled": true
    }
  }
}

Cost Awareness

Free tier models (Big Pickle, Grok Code Fast):

• Minimize server count (3-4 max)
• Disable Hostinger (113 tools = huge context)
• Focus on essential tools

Paid models (Claude Sonnet 4.5):

• $3/1M input tokens, $15/1M output tokens
• 113 tools from Hostinger ≈ 15K tokens ≈ $0.045 per message
• Reserve for complex tasks, switch to free models for routine work

Recommended Configurations

Minimal (Free Models)

json
{
  "registry": true,
  "opencode-sessions": true,
  "theslyprofessor": true,
  "MCP_DOCKER": false
}

Standard (Most Sessions)

json
{
  "registry": true,
  "opencode-sessions": true,
  "theslyprofessor": true,
  "zellij": true,
  "MCP_DOCKER": true,  // Brave + Obsidian
  "hostinger-mcp-server": false
}

Full Power (Complex Tasks)

json
{
  "registry": true,
  "opencode-sessions": true,
  "theslyprofessor": true,
  "zellij": true,
  "outlook-sqlite": true,
  "MCP_DOCKER": true,
  "hostinger-mcp-server": true  // Only for deployment
}

Anthropic's Advanced Tool Use (Nov 2025)

Anthropic released three beta features that address MCP context issues:

Tool Search Tool

Problem: 58 tools from 5 MCP servers = ~55K tokens before conversation starts.

Solution: defer_loading: true on tools. Claude discovers tools on-demand via search.

Results:

• 85% token reduction (77K → 8.7K)
• Opus 4: 49% → 74% accuracy
• Opus 4.5: 79.5% → 88.1% accuracy

json
{
  "tools": [
    {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
    {
      "name": "github.createPullRequest",
      "defer_loading": true  // Only loaded when searched for
    }
  ]
}

Programmatic Tool Calling

Problem: Each tool call = full inference pass. Intermediate results pollute context.

Solution: Claude writes Python code to orchestrate tools. Results processed in sandbox, only final output enters context.

Results:

• 37% token reduction (43K → 27K on complex tasks)
• Parallel execution eliminates round-trips
• Knowledge retrieval: 25.6% → 28.5%

python
# Claude writes orchestration code
team = await get_team_members("engineering")
expenses = await asyncio.gather(*[
    get_expenses(m["id"], "Q3") for m in team
])
# Only final summary enters context, not 2000+ expense records

Tool Use Examples

Problem: JSON schemas define structure, not usage patterns.

Solution: Provide concrete examples showing format conventions, parameter correlations.

Results: 72% → 90% accuracy on complex parameter handling

json
{
  "name": "create_ticket",
  "input_schema": {...},
  "input_examples": [
    {"title": "Critical bug", "priority": "critical", "escalation": {...}},
    {"title": "Feature request", "labels": ["feature-request"]},
    {"title": "Internal task"}  // Minimal example
  ]
}

When to Use Each

Implications for Our Setup

Current approach (good):

• Selective enabling of MCP servers per task type
• Consolidated tools in theslyprofessor server
• Performance monitoring

Future optimizations:

• Add defer_loading: true for Hostinger's 113 tools
• Use Tool Search Tool when total tools >25
• Add input_examples for complex tools like create_article

Theo's Criticism of MCP (Context)

Theo (t3.gg) has discussed concerns about MCP servers consuming context window. Key points:

1. Tool definitions eat tokens - Each tool's JSON schema is injected into context
2. Similar tools confuse models - 20+ similar tools → wrong tool selection
3. Cognitive overload - Studies show LLMs struggle with 10-20+ tools

Our mitigations:

• Only enable needed servers per session
• Consolidate related tools (theslyprofessor has 23 tools, not 23 servers)
• Use descriptive, distinct tool names
• Monitor context usage with /context command

Anthropic's response: The Tool Search Tool and defer_loading directly address these concerns by keeping tools out of context until needed.

See Also

• OpenCode Configuration
• Task Registry Architecture
• ARF (Agents Router Framework)
• Zellij Multi-Pane Workflows
• MCP vs Claude Skills - Choosing the Right Extension Model
• Anthropic: Advanced Tool Use↗