Troubleshooting

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nicobailon/pi-mcp-adapter/llms.txt

Use this file to discover all available pages before exploring further.

​

Server Connection Issues

​

Server Fails to Connect

1. Server not installed For npx servers, the first connection downloads the package. This can fail due to network issues or rate limits.
   Check npm registry

   Pre-install

   npm view @modelcontextprotocol/server-github
   
   Then update config to use the global install:
   {
     "command": "@modelcontextprotocol/server-github",
     "args": []
   }
   
2. 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"]
   }
   
3. Missing environment variables Enable debug mode to see stderr:
   {
     "mcpServers": {
       "my-server": {
         "debug": true
       }
     }
   }
   
   Look for error messages about missing credentials or config.
4. 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”

1. Fix the underlying issue (see above)
2. Force reconnect:
   /mcp reconnect server-name
   
3. Restart Pi

​

HTTP Server Connection Issues

1. 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
   
2. OAuth not completed Run the auth flow:
   /mcp-auth server-name
   
   Follow the instructions to complete OAuth.
3. 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

1. 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
   
2. 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.
3. 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

1. 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" })
   
2. 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
   
3. 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

1. 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
   
2. 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
   
3. 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
   }
   
4. 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

​

Resource Issues

​

Resources Not Appearing as Tools

1. 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.
2. Server has no resources Not all MCP servers expose resources. Check server documentation.
3. 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

1. 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
       }
     }
   }
   
2. 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"
   }
   
3. Cache doesn’t exist First run populates the cache, which requires connecting to all servers. Subsequent runs are faster.

​

High Memory Usage

1. 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
   }
   
2. 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

1. Server startup delay Lazy servers connect on first tool call. Subsequent calls are fast. Solution: Use lifecycle: "eager" for frequently-used servers.
2. npx resolution The adapter resolves npx packages on first connection. This can take 1-2 seconds. Solution: Pre-install or use global packages.
3. 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

1. 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
   
2. Invalid JSON Test syntax:
   cat ~/.pi/agent/mcp.json | jq
   
   If it errors, fix the JSON.
3. Didn’t restart Pi Config is loaded at startup. Restart Pi after changes.
4. 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

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

​

Import Not Working

1. 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
   
2. 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.
3. 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

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

/mcp reconnect server-name

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

​

Cache Corruption

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

​

OAuth Issues

​

OAuth Flow Not Starting

OAuth tokens obtained externally (no browser flow)

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

​

Token Expired

No automatic token refresh

/mcp-auth server-name

​

Idle Timeout Issues

​

Server Disconnects Too Quickly

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

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

​

Server Won’t Disconnect

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

​

Debugging Tips

​

Enable Server Debug Output

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

​

Check Logs

pi 2>&1 | tee pi.log

grep -i mcp pi.log

​

Inspect Cache

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

• Which servers are cached
• Tool counts
• Resource counts

​

Test Server Directly

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

​

Interactive Panel

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

​

Getting Help

1. Check server documentation — many issues are server-specific
2. Enable debug: true to see server stderr
3. Test the server directly to rule out adapter issues
4. 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