Direct Tools

By default, all MCP tools are accessed through the mcp() proxy tool. This keeps your context window small but requires the LLM to discover tools through search. For tools you use frequently, you can register them directly with Pi so they appear alongside built-in tools like read, bash, and edit.

When to use direct tools

Direct tools are ideal for:

Frequently used tools - Tools the LLM should always consider (e.g., github_search_repositories)
Core workflows - Essential tools for your project (e.g., postgres_query for a database project)
Small tool sets - 5-20 tools that form a cohesive capability

Context cost: Each direct tool adds ~150-300 tokens to the system prompt (name + description + parameter schema). Use selectively.

Avoid direct tools when:

Server has 75+ tools (use the proxy or pick specific tools)
Tools are rarely needed
You want to minimize context usage
LLM discovery through search is acceptable

Configuration

Direct tools are configured in your MCP config file (~/.pi/agent/mcp.json or project .pi/mcp.json).

All tools from a server
Specific tools
Global default
Disabled (default)

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "directTools": true
    }
  }
}

Effect: All 26 tools from chrome-devtools become first-class Pi tools:

chrome_devtools_navigate
chrome_devtools_screenshot
chrome_devtools_click
etc.

Still accessible via proxy: Direct tools can also be called through mcp() for consistency.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      },
      "directTools": [
        "search_repositories",
        "get_file_contents",
        "create_or_update_file"
      ]
    }
  }
}

Effect: Only the listed tools are registered directly. Other tools remain proxy-only.

Use original MCP names (without server prefix) in the array. The adapter adds the prefix automatically.

Set a default for all servers, then override per-server:

{
  "settings": {
    "directTools": true
  },
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
      // Inherits directTools: true from settings
    },
    "huge-server": {
      "command": "npx",
      "args": ["-y", "mega-mcp@latest"],
      "directTools": false  // Override: proxy only
    }
  }
}

Effect: All servers use direct tools except huge-server.

Proxy-only mode (no direct tools):

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
      // No directTools field = proxy only
    }
  }
}

Or explicitly disabled:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "directTools": false
    }
  }
}

Interactive configuration

Instead of editing JSON manually, use the interactive panel:

Open the panel

Run the command:

/mcp

Toggle tools

The panel shows all servers with:

Connection status
Tool counts
Direct/Proxy toggles for each tool

Toggle individual tools or entire servers between direct and proxy mode.

Save changes

Changes are written to your config file automatically.

Restart Pi

Direct tools register at startup, so restart Pi to apply changes:

# Exit and restart Pi

The /mcp panel also lets you reconnect servers, initiate OAuth, and view detailed server info.

How direct tools work

Registration from cache

Direct tools register from the metadata cache (~/.pi/agent/mcp-cache.json), not live connections. This means:

No server connections at Pi startup
Instant registration (milliseconds)
Works even if servers are offline

First-time setup: On your first session after adding directTools to a new server, the cache won’t exist yet. Tools will fall back to proxy-only mode and the cache populates in the background. Restart Pi and direct tools will be available. Force cache update: Use /mcp reconnect <server> then restart Pi.

Tool naming

Direct tools follow the same naming rules as proxy tools:

{
  "settings": {
    "toolPrefix": "server"  // or "short" or "none"
  }
}

Prefix Mode	Tool Name
`server` (default)	`chrome_devtools_screenshot`
`short`	`chrome_screenshot` (strips `-mcp` suffix)
`none`	`screenshot`

Name collisions: If a direct tool name conflicts with a built-in Pi tool (like read, bash, mcp), the MCP tool is skipped and a warning is logged. Use prefixes to avoid this.

Duplicate names across servers

If two servers have tools with the same name (after prefixing):

First tool wins
Second tool is skipped
Warning logged: MCP: skipping duplicate direct tool "github_search" from "gitlab"

Solution: Use toolPrefix: "server" mode to namespace tools by server name.

Resource tools

MCP resources are exposed as get_* tools and can be registered directly:

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-server-filesystem",
      "directTools": [
        "read_file",
        "get_documents_readme_md"  // Resource tool
      ]
    }
  }
}

To exclude resource tools:

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-server-filesystem",
      "exposeResources": false,
      "directTools": true
    }
  }
}

Environment override

For testing or temporary changes, override direct tools via environment variable:

# Enable all tools from specific servers
MCP_DIRECT_TOOLS=chrome-devtools,github pi

# Enable specific tools only
MCP_DIRECT_TOOLS=github/search_repositories,github/get_file_contents pi

# Disable all direct tools (proxy only)
MCP_DIRECT_TOOLS=__none__ pi

Syntax:

server-name - All tools from that server
server-name/tool-name - Specific tool from server
Comma-separated list for multiple
__none__ to disable all direct tools

Environment override is temporary and doesn’t modify your config file.

Performance considerations

Context window impact

Each direct tool adds to your system prompt:

Tool Count	Approximate Tokens
5 tools	~1,000 tokens
20 tools	~4,000 tokens
50 tools	~10,000 tokens
100 tools	~20,000 tokens

For comparison:

mcp() proxy tool: ~200 tokens
Pi built-in tools: ~2,000 tokens total

With 100+ direct tools, you’ve consumed ~20% of a 128k context window before the conversation starts. Use selectively.

When to use each approach

Scenario	Recommendation
1-2 frequently used tools	Direct tools
5-20 related tools	Direct tools (good for focused workflows)
50+ tools, use 5 regularly	Direct array: `["tool1", "tool2", ...]`
75+ tools, explore occasionally	Proxy only
Mixed: some frequent, some rare	Hybrid: direct for key tools, proxy for rest

Validation

After configuring direct tools, verify registration:

# List all available tools (including direct MCP tools)
/mcp tools

Or search within Pi:

mcp({ search: "chrome" })
// Direct tools appear WITHOUT [pi tool] prefix (they're MCP tools)

Subagent integration

If you use the Pi subagent extension, agents can request direct tools in their frontmatter:

---
tools:
  - mcp:chrome-devtools
  - mcp:github/search_repositories
  - mcp:github/get_file_contents
---

This dynamically registers tools for that agent only, without polluting the global context. See the subagent extension README for details.

Next steps:

Learn about the mcp() proxy tool
Explore search capabilities
Use commands to manage servers

Get Started

Core Concepts

Configuration

Usage

Advanced

When to use direct tools

Avoid direct tools when:

Configuration

Interactive configuration

How direct tools work

Registration from cache

Tool naming

Duplicate names across servers

Resource tools

Environment override

Performance considerations

Context window impact

When to use each approach

Validation

Subagent integration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Usage

Advanced

Documentation Index

​When to use direct tools

​Avoid direct tools when:

​Configuration

​Interactive configuration

​How direct tools work

​Registration from cache

​Tool naming

​Duplicate names across servers

​Resource tools

​Environment override

​Performance considerations

​Context window impact

​When to use each approach

​Validation

​Subagent integration

Build docs developers (and LLMs) love

When to use direct tools

Avoid direct tools when:

Configuration

Interactive configuration

How direct tools work

Registration from cache

Tool naming

Duplicate names across servers

Resource tools

Environment override

Performance considerations

Context window impact

When to use each approach

Validation

Subagent integration