Skip to main content

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.

​
Overview

If you already have MCP servers configured in other tools, Pi MCP Adapter can import those configurations automatically. This saves you from duplicating server definitions across multiple config files.

​
Supported Import Sources

The adapter supports importing from these tools:
​
cursor
ImportKind
Cursor IDEConfig location: ~/.cursor/mcp.json
​
claude-code
ImportKind
Claude CodeConfig location: ~/.claude/claude_desktop_config.json
​
claude-desktop
ImportKind
Claude DesktopConfig location: ~/Library/Application Support/Claude/claude_desktop_config.json
​
vscode
ImportKind
VS CodeConfig location: .vscode/mcp.json (relative to project)
​
windsurf
ImportKind
WindsurfConfig location: ~/.windsurf/mcp.json
​
codex
ImportKind
CodexConfig location: ~/.codex/config.json

​
Basic Usage

Add an imports array to your mcp.json: 
{
  "imports": ["cursor", "claude-desktop"],
  "mcpServers": {}
}
The adapter will:
  1. Load your Pi config (~/.pi/agent/mcp.json)
  2. Import servers from specified sources
  3. Merge them together (local config takes precedence)
  4. Apply any project-specific overrides from .pi/mcp.json

​
Merge Behavior

Configurations are merged with this precedence order (highest to lowest):
1

Project Config (Highest Priority)

Servers defined in .pi/mcp.json in your project directory
2

User Config

Servers defined in ~/.pi/agent/mcp.json
3

Imported Configs (Lowest Priority)

Servers imported from other tools (processed in order of the imports array)
If the same server name exists in multiple locations, the higher-precedence config wins. This means you can override imported server settings in your local config.

​
Examples

​
Import from Multiple Sources

{
  "imports": [
    "cursor",
    "claude-desktop",
    "vscode"
  ],
  "mcpServers": {
    "my-custom-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"]
    }
  }
}
Result: All servers from Cursor, Claude Desktop, and VS Code are available, plus my-custom-server.

​
Override Imported Server

Cursor’s config (~/.cursor/mcp.json): 
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}
Your Pi config (~/.pi/agent/mcp.json): 
{
  "imports": ["cursor"],
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "directTools": ["search_repositories", "get_file_contents"],
      "lifecycle": "lazy"
    }
  }
}
Result: The github server uses your Pi config settings (with directTools and lifecycle), not Cursor’s.

​
Project-Specific Overrides

Global config (~/.pi/agent/mcp.json): 
{
  "imports": ["claude-desktop"],
  "settings": {
    "toolPrefix": "server",
    "idleTimeout": 10
  }
}
Project config (.pi/mcp.json in your project): 
{
  "settings": {
    "toolPrefix": "short",
    "idleTimeout": 5
  },
  "mcpServers": {
    "project-db": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${PROJECT_DB_URL}"
      },
      "lifecycle": "keep-alive"
    }
  }
}
Result:
  • All Claude Desktop servers are available
  • Settings use project values: toolPrefix: "short", idleTimeout: 5
  • Additional project-db server is available only in this project

​
Import Path Resolution

​
Absolute Paths

Most imports use absolute paths from the home directory: 
"cursor": "~/.cursor/mcp.json"
"claude-desktop": "~/Library/Application Support/Claude/claude_desktop_config.json"
"windsurf": "~/.windsurf/mcp.json"

​
Relative Paths

VS Code uses a project-relative path: 
"vscode": ".vscode/mcp.json"
This is resolved relative to the current working directory (process.cwd()).

​
Config Format Differences

Different tools use different config formats. The adapter handles these automatically:

​
Standard Format (Cursor, Windsurf, VS Code)

{
  "mcpServers": {
    "server-name": { ... }
  }
}
or 
{
  "mcp-servers": {
    "server-name": { ... }
  }
}

​
Claude Desktop Format

{
  "mcpServers": {
    "server-name": { ... }
  }
}

​
Codex Format

{
  "mcpServers": {
    "server-name": { ... }
  }
}
The adapter automatically detects and extracts the mcpServers object regardless of format variations.

​
Error Handling

The adapter gracefully handles import errors:
  • File not found: Silently skipped (no error)
  • Invalid JSON: Warning logged, import skipped
  • Invalid format: Warning logged, import skipped
Failed to import MCP config from cursor: SyntaxError: Unexpected token
Other imports continue processing normally.

​
Import Provenance Tracking

The adapter tracks where each server came from. This is visible in the /mcp interactive panel: 
✓ github (imported from cursor)
✓ filesystem (user config)
✓ project-db (project config)
Provenance affects how config changes are saved:
  • User config servers: Changes written to ~/.pi/agent/mcp.json
  • Imported servers: Changes written to the original import location
  • Project config servers: Changes written to .pi/mcp.json
When you modify an imported server’s directTools setting via /mcp, the change is written back to the original config file (e.g., ~/.cursor/mcp.json). This may affect other tools using that config.

​
Performance

Imports are processed synchronously at startup but are very fast:
  • File reads: ~1-5ms per import
  • JSON parsing: ~1-2ms per import
  • Merge logic: ~1ms
Total overhead: Typically under 20ms even with multiple imports.

​
Complete Example

{
  "imports": [
    "cursor",
    "claude-desktop",
    "vscode"
  ],
  "settings": {
    "toolPrefix": "short",
    "idleTimeout": 15,
    "directTools": false
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      },
      "directTools": ["search_repositories", "get_file_contents"],
      "lifecycle": "lazy"
    },
    "pi-only-server": {
      "command": "npx",
      "args": ["-y", "custom-mcp-server"],
      "lifecycle": "keep-alive"
    }
  }
}
Result:
  • All servers from Cursor, Claude Desktop, and VS Code
  • github server uses Pi-specific settings (overrides any imported github)
  • pi-only-server is only available in Pi
  • Global settings apply to all servers

​
Best Practices

1

Import First

List all imports before defining local servers for clarity
2

Override Selectively

Only redefine imported servers if you need to change their settings
3

Use Project Configs

Put project-specific servers in .pi/mcp.json instead of global config
4

Document Provenance

Use comments (in JSON5 or JSONC) to note which servers are overrides

​
Troubleshooting

​
Imported Servers Not Showing Up

  1. Check file exists: 
    ls ~/.cursor/mcp.json
ls "~/Library/Application Support/Claude/claude_desktop_config.json"
  2. Validate JSON: 
    cat ~/.cursor/mcp.json | jq .
  3. Check import spelling: 
    {
  "imports": ["cursor"]  // Not "cursir" or "Cursor"
}

​
Unexpected Server Behavior

If an imported server behaves differently than expected:
  1. Check local override: Look for the server name in your ~/.pi/agent/mcp.json
  2. Check project override: Look in .pi/mcp.json in your project directory
  3. Check provenance: Run /mcp to see where each server is defined

​
Changes Not Persisting

If you modify imported servers via /mcp and changes disappear:
  • Changes to imported servers are written to the original config file, not Pi’s config
  • If the other tool overwrites its config, your changes may be lost
  • Solution: Define the server in your Pi config to take ownership

​
Next Steps

Server Setup

Configure MCP servers from scratch

Global Settings

Set defaults for toolPrefix, idleTimeout, and directTools

Build docs developers (and LLMs) love

Get started for freeTalk to us