mcp-adapter-tool

Declare MCP servers in settings.json and their tools show up alongside tallow’s built-in tools. No proxy, no extra config, no dependencies. Any standard MCP server that speaks STDIO just works.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    }
  }
}

Tools register as mcp__<server>__<tool>. The filesystem server above would expose mcp__filesystem__read_file, mcp__filesystem__write_file, etc. The LLM sees them like any other tool.

How it works

1. On session start, reads mcpServers from ~/.tallow/settings.json
2. If the project is trusted, merges in .tallow/settings.json (project entries override name conflicts)
3. Spawns each server as a child process (STDIO transport)
4. Sends the MCP initialize handshake and tools/list request
5. Registers every discovered tool with tallow
6. Routes tool calls to the right server
7. Kills all servers on session end

Project trust gate

Project MCP config in .tallow/settings.json is only loaded when the project is trusted. For untrusted or stale projects, the adapter ignores project mcpServers, still loads ~/.tallow/settings.json, and emits a startup warning that project MCP servers were skipped.

Use:

• /trust-project to trust the current project
• /trust-status to inspect trust state/fingerprint
• /untrust-project to revoke trust

Crash handling

If a server process dies mid-session, the adapter attempts one automatic restart on the next tool call. If the restart fails, the server’s tools are marked unavailable and a notification is shown. No retry loops.

SSE cancellation behavior

For type: "sse" servers, request cancellation is fail-fast:

• each POST request has its own AbortController
• request timeouts abort the underlying network POST (not just the Promise)
• stop() aborts the SSE stream and all in-flight POST requests
• endpoint-wait timeout aborts connection setup resources
• timed-out/stopped requests are removed from pending bookkeeping to avoid stale late resolution

Agent-scoped MCP servers

Agents can restrict which MCP servers connect in their subprocess by declaring mcpServers: in frontmatter. This is passed to the subprocess as the PI_MCP_SERVERS environment variable.

---
name: github-helper
description: Agent with GitHub MCP access only
mcpServers: github
---

When PI_MCP_SERVERS is set, the adapter only connects to the listed servers:

PI_MCP_SERVERS=slack,github pi --skill task.md
# Only connects to slack and github servers

Multiple servers can be specified as comma-separated values:

mcpServers: slack, github, linear

Or as a YAML array:

mcpServers:
  - slack
  - github

This feature is used by subagent-tool and agent-commands-tool to control MCP access in agent subprocesses. See those extensions for usage examples.

Inline server definitions (objects instead of string references) are not supported and will show a warning.

Co-located instructions

The extension injects usage documentation into the system prompt via the before_agent_start hook. This includes:

Documentation Lookup (when tool-proxy docs tools are available)

Mandatory workflow for looking up documentation:

1. Check local docs first with search_docs
2. If found, read with get_doc
3. If not found, add with add_doc, then read with get_doc
4. Never use web_fetch for documentation

This applies to all official documentation but not general web content.

MCP Server Policy

Guidelines for managing MCP server configurations in the tool-proxy system.

Tool Proxy Modes

Reference table for the three transport modes (STDIO with Varlock, STDIO with env files, Docker HTTP/SSE) and their configuration.

These instructions are co-located with the extension rather than in a global AGENTS.md file, keeping documentation close to the implementation.

/mcp command

Run /mcp to see all configured servers, their connection state, and their tool lists:

filesystem: ● connected (4 tools)
  mcp__filesystem__read_file
    Read the complete contents of a file
  mcp__filesystem__write_file
    Create or overwrite a file
  mcp__filesystem__list_directory
    List directory contents
  mcp__filesystem__search_files
    Search for files matching a pattern
github: ● connected (8 tools)
  mcp__github__create_issue
    Create a new issue in a repository
  ...