Quick Start

Get 1MCP running in 5 minutes with a basic configuration.

Prerequisites

• Node.js 18+

Basic Setup

1. Create Configuration

   # Create a basic config file
   cat > mcp.json << 'EOF'
   {
     "$schema": "https://docs.1mcp.app/schemas/v1.0.0/mcp-config.json",
     "mcpServers": {
       "filesystem": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
         "tags": ["local", "files"]
       }
     }
   }
   EOF

   JSON Schema Support

   The $schema field enables IDE autocompletion, validation, and inline documentation for your configuration files. Most modern editors (VS Code, WebStorm, etc.) will automatically provide these features when the $schema field is present.

   For local development, you can use a relative path instead:

   "$schema": "./schemas/v1.0.0/mcp-config.json"

2. Start the Server

   npx -y @1mcp/agent --config mcp.json --port 3000

3. Test Connection

   The server is now running on port 3000. You can now connect your MCP client to this port.

That's it! Your 1MCP proxy is now running and aggregating MCP servers.

Project Configuration

For MCP clients that only support STDIO transport (like Claude Desktop), you can use project configuration to streamline proxy connections.

When to Use Project Configuration

Use .1mcprc when your MCP client:

• Cannot connect to HTTP/SSE endpoints directly
• Only supports STDIO transport
• Needs to connect to a running 1MCP server

Prerequisites: You must have a 1MCP server running (npx -y @1mcp/agent serve) for the proxy to connect to.

For projects that regularly use the proxy command, create a .1mcprc file to set default connection settings:

# Create project configuration with preset
cat > .1mcprc << 'EOF'
{
  "$schema": "https://docs.1mcp.app/schemas/v1.0.0/project-config.json",
  "preset": "my-setup"
}
EOF

# Now simply run:
npx -y @1mcp/agent proxy

Project Config Schema

The .1mcprc file also supports JSON Schema for IDE autocompletion. Use the production URL (https://docs.1mcp.app/schemas/v1.0.0/project-config.json) for deployed projects or a relative path (./schemas/v1.0.0/project-config.json) for local development.

We recommend using presets for better configuration management. See the Proxy Command documentation for details.

Next Steps

• Enable Authentication for production use
• Add More Servers to expand capabilities
• Configure Project Settings for team collaboration

Common Issues

Server fails to start?

• Check that Node.js 18+ is installed: node --version
• Verify the config file is valid JSON: cat mcp.json | jq

Can't connect to MCP servers?

• Ensure server commands are executable
• Check server logs for specific error messages