claude-desktop.md•18.8 kB
# Claude Desktop Integration
Learn how to integrate your 1MCP server with Claude Desktop using two different approaches: **local configuration consolidation** (recommended for simplicity) and **remote custom connectors** (for advanced use cases).
## Integration Approaches
### 1. Local Configuration Consolidation (Recommended)
The simplest approach is to consolidate your existing MCP servers into Claude Desktop's configuration using 1MCP as a local proxy. This approach:
- Uses 1MCP proxy to bridge STDIO and HTTP transports
- Automatically configures Claude Desktop to use 1MCP proxy
- Preserves your existing MCP server configurations
- Enables server filtering via global presets
- Works with a running 1MCP HTTP server in the background
### 2. Remote Custom Connectors (Advanced)
For advanced scenarios, you can connect to a remote 1MCP server using Claude Desktop's custom connector feature with HTTP or SSE transport. This approach:
- Requires public HTTPS URL (tunneling/reverse proxy)
- Supports OAuth authentication
- Enables remote access to centralized 1MCP servers
- Useful for team/enterprise deployments
## Why Use 1MCP with Claude Desktop?
- **Unified Access**: Access multiple MCP servers through one endpoint
- **Server Filtering**: Use presets to control which servers are available
- **Centralized Management**: Manage all MCP servers in one place
- **Hot Reloading**: Add/remove servers without restarting Claude Desktop
- **Preset Switching**: Easily switch between different server configurations
## Quick paths
### Choose your approach
- **Local (Recommended)**: 1MCP proxy bridges STDIO↔HTTP with preset-based filtering
- **Remote (Advanced)**: Expose 1MCP over HTTPS and add a custom connector
### Local setup (Recommended)
The local approach uses a two-component setup: a running 1MCP HTTP server and a proxy that bridges to Claude Desktop's STDIO transport.
```bash
# 1. Optionally add some servers first (with tags for filtering)
npx -y @1mcp/agent mcp add context7 --tags=documentation,docs -- npx -y @upstash/context7-mcp
npx -y @1mcp/agent mcp add sequential --tags=thinking,analysis -- npx -y @modelcontextprotocol/server-sequential-thinking
# 2. Create a preset for filtered server access (recommended)
npx -y @1mcp/agent preset create claude-desktop --filter "documentation OR thinking"
# 3. Start 1MCP HTTP server in background
npx -y @1mcp/agent serve &
# 4. Consolidate Claude Desktop to use 1MCP proxy
npx -y @1mcp/agent app consolidate claude-desktop --dry-run # Preview
npx -y @1mcp/agent app consolidate claude-desktop
```
Then restart Claude Desktop. Backups are created automatically; restore anytime:
```bash
npx -y @1mcp/agent app backups claude-desktop
npx -y @1mcp/agent app restore claude-desktop
```
#### Global Preset Configuration
For server filtering, the proxy command uses global presets. You can specify which preset to use when configuring Claude Desktop:
```bash
# Test with a specific preset
npx -y @1mcp/agent proxy --preset claude-desktop
```
This enables global server filtering that applies to all Claude Desktop conversations.
## Remote custom connector (Advanced)
1. Start server
```bash
npx -y @1mcp/agent serve --transport http --port 3001 --external-url https://your-domain.com # dev
npx -y @1mcp/agent serve --transport http --port 3001 --enable-auth --external-url https://your-domain.com # prod
```
Served paths: `/mcp` (Streamable HTTP), `/sse` + `/messages` (SSE), `/oauth` (OAuth), `/health` (health).
2. Expose server over HTTPS
- ngrok: `ngrok http 3001` → use `https://<id>.ngrok-free.app/mcp`
- Reverse proxy:
- nginx: proxy `location /` → `http://localhost:3001` (HTTP/1.1, buffering off)
- Caddy: `reverse_proxy localhost:3001`
- Traefik: router for host → service `1mcp` on port 3001
3. Add connector in Claude Desktop
- Name: any (e.g., "1mcp")
- URL: your public `https://.../mcp`
- Optional: OAuth Client ID/Secret
> Note: OAuth 2.1 validates the issuer URL. Always set `--external-url` to your public origin (for example, `https://your-domain.com` or `https://abc123.ngrok-free.app`).
>
> - Use HTTPS
> - Do not include a path (no `/mcp`)
> - Match exactly what Claude Desktop uses
### Step 2: Add Custom Connector in Claude Desktop
1. **Open Claude Desktop Settings**
- Click on your profile/settings in Claude Desktop
- Navigate to "Connectors" or look for connector management
2. **Add Custom Connector**
- Click "**Add custom connector**"
- You'll see a dialog like this:

3. **Enter Connection Details**
- **Name**: Enter a name for your connector (e.g., "1mcp")
- **URL**: Enter your public HTTPS URL:
- With ngrok: `https://abc123.ngrok-free.app/mcp`
- With reverse proxy: `https://your-domain.com/mcp`
- **OAuth Client ID** (optional): If using authentication
- **OAuth Client Secret** (optional): If using authentication
4. **Confirm Trust**
- Review the security warning
- Click "**Add**" to confirm you trust this connector
### Step 3: Verify Connection
After adding the connector, you should see your 1MCP tools available:

The tools shown will depend on which MCP servers you have configured in your 1MCP instance. Common tools include:
- Context7 library documentation tools
- Sequential thinking tools
- Playwright browser automation
- And any other MCP servers you've added
### Step 4: Use Your Tools
Once connected, your 1MCP tools will appear in Claude Desktop's interface:

You can now use these tools directly in your conversations with Claude.
> 💡 Tip: If any service shows "Awaiting OAuth", open your server's OAuth dashboard at `https://your-domain.com/oauth` and click Authorize for that service. Then retry in Claude Desktop.
## Server quick config
```bash
# Start
npx -y @1mcp/agent serve --transport http --port 3001 --external-url https://your-domain.com
# Enable auth (recommended for production)
npx -y @1mcp/agent serve --transport http --port 3001 --enable-auth --external-url https://your-domain.com
# Filter exposed servers by tags
npx -y @1mcp/agent serve --transport http --port 3001 --tags "context7,sequential" --external-url https://your-domain.com
# Bind to all interfaces (behind reverse proxy)
npx -y @1mcp/agent serve --transport http --port 3001 --host 0.0.0.0 --external-url https://your-domain.com
```
### Authentication
- Enable: `npx -y @1mcp/agent serve --transport http --port 3001 --enable-auth`
- Configure Client ID/Secret in Claude Desktop if needed; OAuth flow is automatic
## Troubleshooting
### Local Configuration Issues
#### Tools Not Appearing After Consolidation
**Symptoms**: Consolidation completes but tools don't appear in Claude Desktop.
**Solutions**:
1. **Restart Claude Desktop**: Ensure you've completely restarted Claude Desktop after consolidation
2. **Check Configuration**: Verify the consolidation worked correctly
```bash
# Check the generated configuration
cat "~/Library/Application Support/Claude/claude_desktop_config.json"
```
3. **Test 1MCP Components**: Verify both HTTP server and proxy are working correctly
```bash
# Check server status
npx -y @1mcp/agent mcp status
# Start HTTP server (if not running)
npx -y @1mcp/agent serve &
# Test proxy command in another terminal
npx -y @1mcp/agent proxy --log-level=debug
```
#### "Consolidation Failed" Error
**Symptoms**: The consolidation command fails with errors.
**Solutions**:
1. **Use Force Flag**: Skip connectivity validation
```bash
npx -y @1mcp/agent app consolidate claude-desktop --force
```
2. **Check Permissions**: Ensure write access to Claude Desktop's config directory
```bash
ls -la "~/Library/Application Support/Claude/"
```
3. **Manual Cleanup**: If consolidation is partially complete
```bash
# Restore from backup
npx -y @1mcp/agent app restore claude-desktop
# Or manually reset
npx -y @1mcp/agent app consolidate claude-desktop --force
```
#### "Configuration Backup Failed" Error
**Symptoms**: Unable to create backup of existing configuration.
**Solutions**:
1. **Check Disk Space**: Ensure sufficient disk space
2. **Check Permissions**: Verify write access to backup directory
3. **Use Force Mode**: Proceed without backup (use with caution)
```bash
npx -y @1mcp/agent app consolidate claude-desktop --force --backup-only
```
#### Proxy Connection Issues
**Symptoms**: Claude Desktop shows connection errors or tools don't appear after consolidation.
**Solutions**:
1. **Verify HTTP Server is Running**: The proxy needs a running 1MCP HTTP server
```bash
# Check if server is running
curl http://localhost:3050/health
# Start server if not running
npx -y @1mcp/agent serve &
```
2. **Test Proxy Command Directly**: Verify proxy can connect to the server
```bash
# Test proxy with debug logging
npx -y @1mcp/agent proxy --log-level=debug
```
3. **Verify Preset and Tags**: Ensure servers have tags that match preset filters
```bash
# List servers with their tags
npx -y @1mcp/agent mcp list
# Check which servers are included in preset
npx -y @1mcp/agent preset show claude-desktop
```
4. **Test Proxy with Preset**: Verify proxy works with the specified preset
```bash
# Test proxy with the preset used in Claude Desktop
npx -y @1mcp/agent proxy --preset claude-desktop --log-level=debug
```
#### Server Discovery Issues
**Symptoms**: Proxy cannot find the running 1MCP HTTP server.
**Solutions**:
1. **Check Common Ports**: Proxy scans ports 3050, 3051, 3052 by default
```bash
# See what's running on common ports
netstat -an | grep -E ':(3050|3051|3052)'
```
2. **Specify Server URL Manually**: Override auto-discovery
```bash
# Test proxy with specific server URL
npx -y @1mcp/agent proxy --url http://localhost:3050/mcp
```
3. **Check Firewalls**: Ensure local firewall isn't blocking connections
### Remote Custom Connector Issues
#### "Failed to Connect" Error
**Symptoms**: Claude Desktop shows connection failed when adding the connector.
**Solutions**:
1. **Check Server Status**: Ensure your 1MCP server is running
```bash
npx -y @1mcp/agent mcp status # Check if servers are running
```
2. **Verify URL**: Ensure the URL is correct and accessible
```bash
# Health endpoints are served at /health (not under /mcp)
curl https://your-domain.com/health # Test basic connectivity
```
3. **Check Firewall**: Ensure the port is open and accessible
#### Tools Not Appearing
**Symptoms**: Connector connects but no tools are visible.
**Solutions**:
1. **Check Server Configuration**: Verify MCP servers are properly configured
```bash
npx -y @1mcp/agent mcp list # List configured servers
```
2. **Restart Both**: Restart both 1MCP and Claude Desktop
#### Authentication Issues
**Symptoms**: OAuth authentication fails or keeps asking for credentials.
**Solutions**:
1. **Check OAuth Configuration**: Ensure OAuth is enabled in 1MCP
2. **Issuer match**: Set `--external-url` to your public HTTPS origin (no path) and ensure it matches Claude’s connector URL origin exactly
3. **Verify Credentials**: Double-check Client ID and Secret in Claude Desktop
4. **Clear Cache**: Try removing and re-adding the connector
### Debugging Steps
1. **Test Direct Connection**:
```bash
# Test your exposed HTTPS endpoint
curl -X POST https://your-domain.com/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0","id": 1,"method": "initialize","params": {"protocolVersion": "2025-06-18","capabilities": {},"clientInfo": {"name": "ExampleClient","title": "Example Client Display Name","version": "1.0.0"}}}'
```
2. **Check Server Logs**:
```bash
ONE_MCP_LOG_LEVEL=debug npx -y @1mcp/agent serve --transport http --port 3001
```
3. **Health Check**:
```bash
# Check if server is responding through your proxy/tunnel
curl https://your-domain.com/health
```
## Security Considerations
### Production Deployment
1. HTTPS via reverse proxy (nginx/Caddy/Traefik)
2. Enable OAuth in production: `--enable-auth`
3. Harden network: firewall, VPN/private networks, rate limiting at proxy, bind to localhost when proxied
### Trust and Permissions
- **Review Carefully**: Only connect to trusted 1MCP servers
- **Understand Permissions**: Review what tools will be accessible
- **Regular Audits**: Periodically review connected connectors and their permissions
## Advanced Usage
### Multiple Environments
You can add multiple 1MCP connectors for different environments:
1. **Development Environment**:
- Name: "1MCP Dev"
- URL: `https://dev-abc123.ngrok-free.app/mcp` (using ngrok)
2. **Production Environment**:
- Name: "1MCP Prod"
- URL: `https://prod-server.com/mcp`
- OAuth credentials for production
### Server Filtering
Control which tools are available by filtering servers:
```bash
# Only expose specific capabilities
npx -y @1mcp/agent serve --transport http --port 3001 --tags "context7,sequential"
```
## Best Practices
### Local
- Start HTTP server first → `serve` (uses default port 3050)
- Create presets for server filtering → `preset create`
- Use `--preset` parameter in proxy command for filtering
- Preview consolidation → `--dry-run`
- Backups are automatic; restart Claude Desktop after consolidation
- Keep agent updated; monitor with `mcp status`
### Remote
- Start simple (no auth), then add OAuth + HTTPS for prod
- Health checks + monitoring
- Review permissions regularly; keep servers updated
## Examples
### Local (recommended)
```bash
# 1. Install 1MCP agent
npm install -g @1mcp/agent
# 2. Add some useful MCP servers (with tags for filtering)
npx -y @1mcp/agent mcp add context7 --tags=documentation,docs -- npx -y @upstash/context7-mcp
npx -y @1mcp/agent mcp add sequential --tags=thinking,analysis -- npx -y @modelcontextprotocol/server-sequential-thinking
npx -y @1mcp/agent mcp add playwright --tags=browser,testing -- npx -y @playwright/mcp
# 3. Create a preset for Claude Desktop
npx -y @1mcp/agent preset create claude-desktop --filter "documentation OR thinking OR browser"
# 4. Start 1MCP HTTP server
npx -y @1mcp/agent serve
# 5. In another terminal, preview consolidation
npx -y @1mcp/agent app consolidate claude-desktop --dry-run
# 6. Consolidate Claude Desktop configuration
npx -y @1mcp/agent app consolidate claude-desktop
# 7. Restart Claude Desktop
# 8. Verify tools are available in Claude Desktop
npx -y @1mcp/agent mcp status # Check server health
```
Your Claude Desktop will now use the following configuration automatically:
```json
{
"mcpServers": {
"1mcp": {
"command": "npx",
"args": ["-y", "@1mcp/agent", "proxy", "--preset", "claude-desktop"]
}
}
}
```
#### With Custom Presets
You can specify any preset when configuring Claude Desktop:
```json
{
"mcpServers": {
"1mcp": {
"command": "npx",
"args": ["-y", "@1mcp/agent", "proxy", "--preset", "my-custom-preset"]
}
}
}
```
Create different presets for different use cases:
```bash
# Development preset
npx -y @1mcp/agent preset create dev --filter "filesystem OR git OR testing"
# Documentation preset
npx -y @1mcp/agent preset create docs --filter "documentation OR writing"
# Analysis preset
npx -y @1mcp/agent preset create analysis --filter "data OR thinking"
```
### Remote + ngrok
For development setups where you need remote access:
```bash
# 1. Install and configure 1MCP
npm install -g @1mcp/agent
npx -y @1mcp/agent mcp add context7 -- npx -y @upstash/context7-mcp
npx -y @1mcp/agent mcp add sequential -- npx -y @modelcontextprotocol/server-sequential-thinking
# 2. Expose via ngrok
ngrok http 3001
# 3. Start server, use the URL from ngrok
npx -y @1mcp/agent serve --transport http --port 3001 --external-url https://abc123.ngrok-free.app
# 4. Add connector in Claude Desktop:
# - Name: "My 1MCP Server"
# - URL: "https://abc123.ngrok-free.app/mcp" (use the URL from ngrok)
# 5. Verify tools are available in Claude Desktop
```
### Production + Nginx
```bash
# 1. Start 1MCP server (bind to localhost for security)
npx -y @1mcp/agent serve --transport http --port 3001 --enable-auth --external-url https://your-domain.com
# 2. Configure nginx to proxy HTTPS to HTTP
# 3. Add connector in Claude Desktop:
# - Name: "Production 1MCP"
# - URL: "https://your-domain.com/mcp"
# - Add OAuth credentials
# 4. Verify tools are available in Claude Desktop
```
## Getting Help
If you encounter issues:
1. Check the [troubleshooting section](#troubleshooting) above
2. For **local configuration issues**:
- Try `npx -y @1mcp/agent app consolidate claude-desktop --force`
- Check `npx -y @1mcp/agent mcp status` for server health
- Use `npx -y @1mcp/agent app restore claude-desktop` to rollback
3. For **remote connector issues**:
- Review Anthropic's documentation on:
- [Custom connectors via remote MCP servers](https://support.anthropic.com/en/articles/11503834-building-custom-connectors-via-remote-mcp-servers)
- [Browsing and connecting to tools](https://support.anthropic.com/en/articles/11724452-browsing-and-connecting-to-tools-from-the-directory)
4. Open an issue on our [GitHub repository](https://github.com/1mcp-app/agent)
5. Check the [1MCP documentation](/guide/getting-started) for server configuration help
## Which Approach Should I Use?
### Choose **Local Configuration Consolidation** if:
- ✅ You want preset-based server filtering
- ✅ You're using Claude Desktop on your local machine
- ✅ You don't need remote access
- ✅ You want centralized server management
- ✅ You prefer running HTTP server with proxy bridge to Claude Desktop
### Choose **Remote Custom Connectors** if:
- ✅ You have a Claude Pro/Max/Team/Enterprise plan
- ✅ You need to access a centralized 1MCP server
- ✅ You're comfortable with networking/HTTPS setup
- ✅ You want to share MCP servers across multiple clients
- ✅ You need OAuth authentication
## Next Steps
- Learn about the [Proxy Command](/commands/proxy) for detailed configuration options
- Explore [server filtering options](/guide/advanced/server-filtering) for presets and tags
- Set up [server management](/guide/essentials/server-management) for your MCP servers
- Configure [app consolidation](./app-consolidation) for seamless management of other apps
- Learn about [authentication configuration](/guide/advanced/authentication) for remote setups