Troubleshooting - Pi MCP Adapter

Server Connection Issues

Server Fails to Connect

Symptom: Error message like Failed to connect to "server-name": <error> Common Causes:

Server not installed For npx servers, the first connection downloads the package. This can fail due to network issues or rate limits.
npm view @modelcontextprotocol/server-github
Then update config to use the global install:
```
{
  "command": "@modelcontextprotocol/server-github",
  "args": []
}
```

Invalid command path Check that the command exists:

which node
which npx

Use absolute paths if needed:

{
  "command": "/usr/local/bin/node",
  "args": ["server.js"]
}

Missing environment variables Enable debug mode to see stderr:
```
{
  "mcpServers": {
    "my-server": {
      "debug": true
    }
  }
}
```
Look for error messages about missing credentials or config.
Server process crashes immediately Test the server directly:
```
npx -y @modelcontextprotocol/server-github
```
It should start and wait for input. If it crashes, the issue is with the server itself, not the adapter.

Server Shows “Failed Xs Ago”

Symptom: /mcp shows “failed 120s ago” instead of connected/cached. Cause: The adapter tracks connection failures and applies a 60-second backoff to avoid spamming reconnections. From index.ts:34, failed servers are tracked with timestamps. The adapter won’t retry lazy connections for 60 seconds after a failure. Solution:

Fix the underlying issue (see above)
Force reconnect:
```
/mcp reconnect server-name
```
Restart Pi

The backoff only applies to lazy connections (automatic retry on tool call). You can always force reconnect with /mcp reconnect.

HTTP Server Connection Issues

Symptom: HTTP/SSE transport fails with auth errors. Common Causes:

Missing bearer token

{
  "url": "https://api.example.com/mcp",
  "auth": "bearer",
  "bearerTokenEnv": "API_TOKEN"  // Make sure this is set!
}

export API_TOKEN="your-token"
pi

OAuth not completed Run the auth flow:
```
/mcp-auth server-name
```
Follow the instructions to complete OAuth.
Wrong transport The adapter tries StreamableHTTP first, then falls back to SSE. If the server only supports one:
- Check server documentation for required transport
- Some servers need specific headers (set in headers field)

Tool Discovery Issues

Tools Not Showing in Search

Symptom: mcp({ search: "..." }) returns no results for tools you expect. Causes:

Metadata not cached Check if the server is cached:

cat ~/.pi/agent/mcp-cache.json | jq '.servers["server-name"]'

If missing, connect to populate cache:

/mcp reconnect server-name

Server has no tools List the server:
```
mcp({ server: "server-name" })
```
If it shows 0 tools, the server isn’t exposing any. Check server configuration.
Search query doesn’t match From index.ts:734-761, search splits on whitespace and ORs the terms with regex. Try:
- Single keywords: mcp({ search: "screenshot" })
- Multiple terms: mcp({ search: "list table" }) (matches “list_tables”)
- Regex mode: mcp({ search: "^get_", regex: true })

Tool Not Found When Calling

Symptom: mcp({ tool: "tool_name" }) returns “Tool ‘tool_name’ not found”. Causes:

Wrong tool name Tool names are prefixed by default. If toolPrefix: "server", the tool is:
```
server_name_original_tool_name
```
Use search to find the exact name:
```
mcp({ search: "original_tool" })
```
Server not connected/cached The adapter lazy-connects on tool calls, but if the server previously failed, it won’t retry for 60s. Force reconnect:
```
/mcp reconnect server-name
```
Hyphen/underscore mismatch From index.ts:42-48, the adapter normalizes hyphens and underscores. These should work:
- mcp({ tool: "resolve-library-id" })
- mcp({ tool: "resolve_library_id" })
But if neither works, check the exact name with:
```
mcp({ describe: "resolve_library_id" })
```

Direct Tools Issues

Direct Tools Not Registering

Symptom: Set directTools: true but tools don’t appear in Pi’s tool list. Causes:

Cache doesn’t exist Direct tools register from the metadata cache at startup. If the cache is empty, tools won’t register. From index.ts:1261-1298, the adapter bootstraps missing caches in the background on first run. Solution: Connect to the server and restart Pi:
```
/mcp reconnect server-name
# Restart Pi
```
Cache is stale From metadata-cache.ts, the cache includes a hash of server config. If you changed the config, the cache is invalidated. Solution: Reconnect to refresh cache:
```
/mcp reconnect server-name
# Restart Pi
```
Tool name collision From index.ts:138-146, builtin names are protected:
- read, bash, edit, write, grep, find, ls, mcp
If a tool has the same prefixed name as a builtin, it’s skipped with a warning:
```
MCP: skipping direct tool "bash" (collides with builtin)
```
Solution: Use toolPrefix: "server" to namespace tools, or list specific tools:
```
{
  "directTools": ["tool1", "tool2"]  // Exclude colliding tools
}
```
Duplicate tool names If two servers expose tools with the same prefixed name:
```
MCP: skipping duplicate direct tool "server_query" from "postgres2"
```
Solution: Use toolPrefix: "server" (full server name prefix) or explicitly list tools.

MCP_DIRECT_TOOLS Not Working

See Environment Variables for details on MCP_DIRECT_TOOLS.

Resource Issues

Resources Not Appearing as Tools

Symptom: MCP resources don’t show up in tool list. Causes:

exposeResources: false Check server config:

{
  "mcpServers": {
    "my-server": {
      "exposeResources": false  // ❌ Resources disabled
    }
  }
}

Default is true. Only set to false if you want to disable resource tools.

Server has no resources Not all MCP servers expose resources. Check server documentation.
Resource naming From resource-tools.ts, resources are exposed as tools with names like:
```
get_<resource_name>
```
The resource name is sanitized (special chars replaced with underscores). Search for get_ to find them:
```
mcp({ search: "get_", regex: true })
```

Performance Issues

Slow Startup

Symptom: Pi takes 10+ seconds to start. Causes:

Too many eager/keep-alive servers From index.ts:1206-1226, the adapter connects to all eager and keep-alive servers at startup in parallel (max 10 concurrent). Solution: Use lazy lifecycle for most servers:
```
{
  "mcpServers": {
    "rarely-used": {
      "lifecycle": "lazy"  // Don't connect at startup
    }
  }
}
```
npx overhead From the README, npx-based servers have ~143 MB parent process overhead, but the adapter resolves them to direct binary paths. If still slow, pre-install globally:
```
npm install -g @modelcontextprotocol/server-github
```
Update config:
```
{
  "command": "@modelcontextprotocol/server-github"
}
```
Cache doesn’t exist First run populates the cache, which requires connecting to all servers. Subsequent runs are faster.

High Memory Usage

Symptom: Pi process uses 500+ MB RAM. Causes:

Too many keep-alive servers Each connected server is a separate process. If you have 10 servers with lifecycle: "keep-alive", you have 10+ processes running. Solution: Use lazy lifecycle and rely on the cache:
```
{
  "lifecycle": "lazy",
  "idleTimeout": 5  // Disconnect after 5 minutes
}
```
Large MCP responses If a tool returns megabytes of data (e.g., database dump), it’s kept in memory. Solution: Ask the LLM to paginate or filter results.

Slow Tool Calls

Symptom: Tool calls take 5+ seconds. Causes:

Server startup delay Lazy servers connect on first tool call. Subsequent calls are fast. Solution: Use lifecycle: "eager" for frequently-used servers.
npx resolution The adapter resolves npx packages on first connection. This can take 1-2 seconds. Solution: Pre-install or use global packages.
Network latency (HTTP servers) HTTP/SSE transport adds round-trip latency. Solution: Use stdio transport if possible, or keep the connection alive:
```
{
  "lifecycle": "keep-alive"
}
```

Configuration Issues

Config Not Loading

Symptom: Changes to mcp.json don’t apply. Causes:

Wrong file path Default is ~/.pi/agent/mcp.json. Check:
```
ls -la ~/.pi/agent/mcp.json
```
You can override with --mcp-config:
```
pi --mcp-config /path/to/mcp.json
```
Invalid JSON Test syntax:
```
cat ~/.pi/agent/mcp.json | jq
```
If it errors, fix the JSON.
Didn’t restart Pi Config is loaded at startup. Restart Pi after changes.
Config warnings in console From config.ts:30-32, parse errors are logged:
```
Failed to load MCP config from <path>: <error>
```
Check Pi’s stderr for warnings.

Settings Not Applying

Symptom: toolPrefix or idleTimeout doesn’t work. Solution: Settings go in the settings object, not at root level:

{
  "toolPrefix": "short",
  "mcpServers": { }
}

Import Not Working

Symptom: imports array doesn’t load other configs. Causes:

Config file doesn’t exist From config.ts:11-18, import paths are:

Import Kind	Path
`cursor`	`~/.cursor/mcp.json`
`claude-code`	`~/.claude/claude_desktop_config.json`
`claude-desktop`	`~/Library/Application Support/Claude/claude_desktop_config.json`
`vscode`	`.vscode/mcp.json` (project-relative)
`windsurf`	`~/.windsurf/mcp.json`
`codex`	`~/.codex/config.json`

Check if the file exists:

ls -la ~/.cursor/mcp.json

Invalid JSON in imported file From config.ts:47-59, import errors are logged but don’t fail the entire config load:
```
Failed to import MCP config from cursor: <error>
```
Check Pi’s stderr for warnings.
Wrong format Imported configs must have mcpServers key. Claude Desktop uses mcpServers, Cursor uses mcp-servers or mcpServers. Both are supported.

Cache Issues

Cache Not Updating

Symptom: Tool list doesn’t reflect server changes. Cause: The cache (~/.pi/agent/mcp-cache.json) is validated against a hash of the server config. If the hash matches, the cache is used even if the server changed. From metadata-cache.ts, the hash includes:

command, args, url
env (keys only, not values)
exposeResources

Changing these invalidates the cache. But changing lifecycle, idleTimeout, or debug does not. Solution: Force refresh:

/mcp reconnect server-name

Or delete the cache:

rm ~/.pi/agent/mcp-cache.json
# Restart Pi

Cache Corruption

Symptom: Adapter errors on startup with cache-related messages. Solution: Delete and rebuild:

rm ~/.pi/agent/mcp-cache.json
pi
# Cache rebuilds automatically

The cache is just an optimization. Deleting it is safe.

OAuth Issues

OAuth Flow Not Starting

Symptom: /mcp-auth server-name shows error or does nothing. Cause: OAuth implementation is minimal. From the README:

OAuth tokens obtained externally (no browser flow)

The adapter doesn’t have a built-in browser flow. You need to:

Obtain the token manually (via server docs)
Store it with /mcp-auth

Some servers have helper commands. Check server documentation.

Token Expired

Symptom: HTTP server returns 401 Unauthorized. Cause: OAuth tokens expire. From the README:

No automatic token refresh

Solution: Re-authenticate:

/mcp-auth server-name

Idle Timeout Issues

Server Disconnects Too Quickly

Symptom: Server shows “idle” between tool calls. Cause: Default idle timeout is 10 minutes. From lifecycle.ts, the adapter tracks last activity and disconnects idle servers. Solution: Increase timeout or disable:

{
  "mcpServers": {
    "my-server": {
      "idleTimeout": 0  // Never disconnect
    }
  }
}

Or use keep-alive:

{
  "lifecycle": "keep-alive"  // Never idle-disconnect
}

Server Won’t Disconnect

Symptom: Server stays connected even when unused. Cause: idleTimeout: 0 or lifecycle: "keep-alive". Solution: Set a timeout:

{
  "lifecycle": "lazy",
  "idleTimeout": 10
}

Debugging Tips

Enable Server Debug Output

Add debug: true to see server stderr:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "debug": true
    }
  }
}

Restart Pi and watch for error messages.

Check Logs

Pi logs to stderr. Run with output visible:

pi 2>&1 | tee pi.log

Search for “MCP” in the log:

grep -i mcp pi.log

Inspect Cache

The cache is human-readable JSON:

cat ~/.pi/agent/mcp-cache.json | jq

Check:

Which servers are cached
Tool counts
Resource counts

Test Server Directly

Run the server outside Pi to isolate issues:

node server.js
# Or
npx -y @modelcontextprotocol/server-github

The server should start and wait for input. If it crashes, the problem is with the server, not the adapter.

Interactive Panel

Use /mcp to open the interactive panel. It shows:

Server status (connected/idle/failed)
Tool counts
Direct vs proxy tools
Reconnect buttons

This is the fastest way to diagnose connection issues.

Getting Help

If you’re stuck:

Check server documentation — many issues are server-specific
Enable debug: true to see server stderr
Test the server directly to rule out adapter issues
File an issue at https://github.com/badlogic/pi-mcp-adapter with:
- Pi version (pi --version)
- Server config (sanitize secrets)
- Error messages from logs
- Output of /mcp command

Get Started

Core Concepts

Configuration

Usage

Advanced

Documentation Index

​Server Connection Issues

​Server Fails to Connect

​Server Shows “Failed Xs Ago”

​HTTP Server Connection Issues

​Tool Discovery Issues

​Tools Not Showing in Search

​Tool Not Found When Calling

​Direct Tools Issues

​Direct Tools Not Registering

​MCP_DIRECT_TOOLS Not Working

​Resource Issues

​Resources Not Appearing as Tools

​Performance Issues

​Slow Startup

​High Memory Usage

​Slow Tool Calls

​Configuration Issues

​Config Not Loading

​Settings Not Applying

​Import Not Working

​Cache Issues

​Cache Not Updating

​Cache Corruption

​OAuth Issues

​OAuth Flow Not Starting

​Token Expired

​Idle Timeout Issues

​Server Disconnects Too Quickly

​Server Won’t Disconnect

​Debugging Tips

​Enable Server Debug Output

​Check Logs

​Inspect Cache

​Test Server Directly

​Interactive Panel

​Getting Help

Server Connection Issues

Server Fails to Connect

Server Shows “Failed Xs Ago”

HTTP Server Connection Issues

Tool Discovery Issues

Tools Not Showing in Search

Tool Not Found When Calling

Direct Tools Issues

Direct Tools Not Registering

MCP_DIRECT_TOOLS Not Working

Resource Issues

Resources Not Appearing as Tools

Performance Issues

Slow Startup

High Memory Usage

Slow Tool Calls

Configuration Issues

Config Not Loading

Settings Not Applying

Import Not Working

Cache Issues

Cache Not Updating

Cache Corruption

OAuth Issues

OAuth Flow Not Starting

Token Expired

Idle Timeout Issues

Server Disconnects Too Quickly

Server Won’t Disconnect

Debugging Tips

Enable Server Debug Output

Check Logs

Inspect Cache

Test Server Directly

Interactive Panel

Getting Help