An MCP (Model Context Protocol) server that acts as a proxy between IDEs and the mcpd daemon, exposing all mcpd-managed MCP servers through a unified interface.
┌─────────────┐ STDIO/JSON-RPC ┌──────────────┐ HTTP/REST ┌──────────┐
│ IDE/Editor │ ◄─────────────────► │ mcpd-proxy │ ◄───────────────►│ mcpd │
│ (VS Code, │ MCP Protocol │ MCP Server │ Uses mcpd SDK │ daemon │
│ Cursor) │ │ │ │ │
└─────────────┘ └──────────────┘ └──────────┘
mcpd-proxy aggregates tools, resources, and prompts from multiple MCP servers managed by mcpd into a single MCP interface, making it easy for IDEs to access all capabilities without managing individual server connections.
- Unified Interface: Single MCP server exposing all
mcpd-managed capabilities - Tool Aggregation: Tools from all servers with
server__toolnaming convention - Resource Aggregation: Resources from all servers with
server__resourcenaming andmcpd://URIs - Prompt Aggregation: Prompts from all servers with
server__promptnaming convention - Efficient Caching: Leverages SDK caching for health checks and tool schemas
- Zero Configuration: Works out of the box with sensible defaults
- TypeScript: Built with
TypeScriptfor type safety
Node.js22.10.0 or higher (latest 22.x recommended)mcpddaemon running and accessiblemcpdSDK (automatically installed as a dependency)
# Global installation
npm install -g @mozilla-ai/mcpd-proxy
# Or use directly with npx
npx @mozilla-ai/mcpd-proxy# Clone the repository
git clone https://github.com/mozilla-ai/mcpd-proxy.git
cd mcpd-proxy
# Install dependencies
npm install
# Build the project
npm run buildmcpd-proxy is configured via environment variables:
| Variable | Description | Default |
|---|---|---|
MCPD_ADDR |
mcpd daemon address |
http://localhost:8090 |
MCPD_API_KEY |
Optional API key for mcpd authentication |
(not set) |
# Using npm package (recommended)
npx @mozilla-ai/mcpd-proxy
# With custom mcpd address
MCPD_ADDR=http://localhost:8090 npx @mozilla-ai/mcpd-proxy
# With API key
MCPD_ADDR=http://localhost:8090 MCPD_API_KEY=your-key npx @mozilla-ai/mcpd-proxy
# From source build
node dist/index.mjs
# From source with custom address
MCPD_ADDR=http://localhost:8090 node dist/index.mjsAdd to your VS Code MCP settings file (location varies by platform):
{
"servers": {
"mcpd": {
"type": "stdio",
"command": "npx",
"args": ["@mozilla-ai/mcpd-proxy"],
"env": {
"MCPD_ADDR": "http://localhost:8090"
}
}
}
}Or if building from source:
{
"servers": {
"mcpd": {
"type": "stdio",
"command": "node",
"args": ["<path-to-mcpd-proxy>/dist/index.mjs"],
"env": {
"MCPD_ADDR": "http://localhost:8090"
}
}
}
}Replace <path-to-mcpd-proxy> with the absolute path to your installation.
Reload VS Code: Cmd+Shift+P → "Developer: Reload Window"
Verify the connection in the MCP panel to see available tools.
Create or edit .cursor/mcp.json in your project directory, or ~/.cursor/mcp.json for global configuration:
{
"mcpServers": {
"mcpd": {
"command": "npx",
"args": ["@mozilla-ai/mcpd-proxy"],
"env": {
"MCPD_ADDR": "http://localhost:8090"
}
}
}
}Or if building from source:
{
"mcpServers": {
"mcpd": {
"command": "node",
"args": ["<path-to-mcpd-proxy>/dist/index.mjs"],
"env": {
"MCPD_ADDR": "http://localhost:8090"
}
}
}
}Replace <path-to-mcpd-proxy> with the absolute path to your installation, or use ${workspaceFolder} for relative paths.
Reload Cursor to apply the configuration.
See examples/ folder for configuration examples.
mcpd-proxy/
├── src/
│ ├── index.ts # CLI entry point
│ ├── server.ts # MCP server implementation
│ ├── config.ts # Configuration loader
│ └── apiPaths.ts # API endpoint constants
├── tests/
│ └── unit/ # Unit test files
│ ├── aggregation.test.ts
│ ├── apiPaths.test.ts
│ ├── config.test.ts
│ ├── parsers.test.ts
│ └── server.test.ts
├── .github/
│ └── workflows/ # GitHub Actions workflows
│ ├── tests.yaml
│ ├── lint.yaml
│ └── release.yaml
├── examples/
│ ├── vscode-config.json # VS Code configuration example
│ └── cursor-config.json # Cursor configuration example
├── dist/ # Build output (gitignored)
├── package.json # npm package configuration
├── package-lock.json # npm dependency lock file
├── tsconfig.json # TypeScript compiler configuration
├── tsconfig.test.json # TypeScript test configuration
├── vitest.config.ts # Vitest test configuration
├── vite.config.mts # Vite build configuration
├── eslint.config.mts # ESLint configuration
├── .prettierignore # Prettier ignore patterns
├── .gitignore # Git ignore patterns
└── README.md # This file
# Install dependencies
npm install
# Build once
npm run build
# Watch mode (auto-rebuild on changes)
npm run dev
# Run tests
npm test
# Run tests in watch mode
npm run test:watch
# Type check without building
npm run typecheck
# Lint code
npm run lint
# Format code
npm run formatTest the MCP protocol directly using JSON-RPC over stdio:
# Test initialize
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node dist/index.mjs
# Test list tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node dist/index.mjsTools are exposed with the format: {server}__{tool_name}
Examples:
time__get_current_time-get_current_timetool fromtimeservergithub__create_issue-create_issuetool fromgithubserverfetch__get_url-get_urltool fromfetchserver
This naming convention prevents tool name collisions between servers and makes it clear which server provides each tool.
Resources use a custom URI scheme: mcpd://{server}/{resource_uri}
Examples:
mcpd://filesystem/documents/file.txtmcpd://database/users/123
Prompts follow the same naming convention as tools: {server}__{prompt_name}
mcpd-proxy creates a single instance of McpdClient at startup and reuses it for all requests. This is essential for:
- Caching: Health check cache (10s
TTL) and tool schema cache (60sTTL) - Performance: Avoids creating new
HTTPconnections for each request - Efficiency: Reduces load on
mcpddaemon
const mcpdClient = new McpdClient({
apiEndpoint: config.mcpdAddr,
apiKey: config.mcpdApiKey,
healthCacheTtl: 10,
serverCacheTtl: 60,
});The proxy implements the following MCP protocol handlers:
initialize- Handshake with IDE, declares capabilitiestools/list- Aggregates tools from allmcpdserverstools/call- Parses tool name and forwards tomcpdresources/list- Aggregates resources from all serversresources/read- Forwards resource read requests tomcpdprompts/list- Aggregates prompts from all serversprompts/get- Forwards prompt requests tomcpdping- Health check endpoint
Cause: mcpd daemon is not running or not accessible
Solution:
- Verify
mcpdis running:curl http://localhost:8090/api/v1/servers - Check
MCPD_ADDRenvironment variable is correct - Ensure no firewall blocking the connection
Cause: Requested server doesn't exist in mcpd
Solution:
- List available servers:
curl http://localhost:8090/api/v1/servers - Check server is configured in
mcpd - Verify server is healthy:
curl http://localhost:8090/api/v1/health/servers/<server-name>
Cause: VS Code may not have recognized the MCP server
Solution:
- Check VS Code developer console for errors (Help → Toggle Developer Tools)
- Verify the path to
dist/index.mjsis correct and absolute (if building from source) - Reload VS Code:
Cmd+Shift+P→ "Developer: Reload Window" - Check
mcpddaemon is running and accessible
Cause: Server may be unhealthy or tool doesn't exist
Solution:
- Check server health via
mcpdAPI - Verify tool exists on the server
- Check
mcpdlogs for errors
- Dynamic tool list updates (
notifications/tools/list_changed) - Server filtering via
MCPD_SERVERSenvironment variable - Improved unhealthy server handling
mcpd- The MCP daemon this proxy connects tomcpd-sdk-javascript-TypeScriptSDK formcpdmcpd-sdk-python- Python SDK formcpd
Apache-2.0
See the main mcpd repository for contribution guidelines.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}