Claude Desktop

Related Topics: Quickstart (first connection) | Deployment (production setup) | Common Tasks (quick how-to)

Claude Desktop has native Model Context Protocol (MCP) support, making it the easiest way to connect your MXCP endpoints to an AI assistant.

Configuration

Find the Config File

Claude Desktop’s configuration is stored in:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Basic Configuration

Add your MXCP server to the configuration file:

{
  "mcpServers": {
    "my-project": {
      "command": "mxcp",
      "args": ["serve", "--transport", "stdio"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

Important: Use absolute paths for cwd. Relative paths will fail.

Virtual Environment

If MXCP is installed in a virtual environment:

{
  "mcpServers": {
    "my-project": {
      "command": "bash",
      "args": [
        "-c",
        "cd /path/to/project && source /path/to/.venv/bin/activate && mxcp serve --transport stdio"
      ]
    }
  }
}

Or use the full path to the Python executable:

{
  "mcpServers": {
    "my-project": {
      "command": "/path/to/.venv/bin/mxcp",
      "args": ["serve", "--transport", "stdio"],
      "cwd": "/path/to/project"
    }
  }
}

Multiple Servers

Connect multiple MXCP projects:

{
  "mcpServers": {
    "analytics": {
      "command": "mxcp",
      "args": ["serve", "--transport", "stdio"],
      "cwd": "/path/to/analytics-project"
    },
    "customer-support": {
      "command": "mxcp",
      "args": ["serve", "--transport", "stdio"],
      "cwd": "/path/to/support-project"
    },
    "inventory": {
      "command": "mxcp",
      "args": ["serve", "--transport", "stdio"],
      "cwd": "/path/to/inventory-project"
    }
  }
}

Environment Variables

Pass environment variables to the server:

{
  "mcpServers": {
    "my-project": {
      "command": "mxcp",
      "args": ["serve", "--transport", "stdio"],
      "cwd": "/path/to/project",
      "env": {
        "MXCP_PROFILE": "production",
        "DATABASE_URL": "postgresql://localhost/mydb"
      }
    }
  }
}

Activation

After modifying the configuration:

Save the configuration file
Restart Claude Desktop completely (quit and reopen)
Verify connection in Claude Desktop

You should see your tools available in Claude’s interface.

Usage

Tool Discovery

Claude automatically discovers your MXCP tools. Ask Claude:

“What tools do you have access to?”

Claude will list all available tools from your MXCP server.

Calling Tools

Simply ask Claude to use your tools naturally:

“Can you find the user with ID 123?”

Claude will call the appropriate tool and return results.

Resource Access

Access MXCP resources:

“Show me the user profile for alice@example.com”

Using Prompts

Invoke MXCP prompts:

“Use the customer-analysis prompt to analyze this data”

Configuration Options

Transport Options

{
  "mcpServers": {
    "my-project": {
      "command": "mxcp",
      "args": [
        "serve",
        "--transport", "stdio",
        "--log-level", "INFO"
      ],
      "cwd": "/path/to/project"
    }
  }
}

Debug Mode

Enable verbose logging:

{
  "mcpServers": {
    "my-project": {
      "command": "mxcp",
      "args": [
        "serve",
        "--transport", "stdio",
        "--log-level", "DEBUG"
      ],
      "cwd": "/path/to/project"
    }
  }
}

Profile Selection

Use a specific MXCP profile:

{
  "mcpServers": {
    "my-project": {
      "command": "mxcp",
      "args": [
        "serve",
        "--transport", "stdio",
        "--profile", "production"
      ],
      "cwd": "/path/to/project"
    }
  }
}

Troubleshooting

Server Not Connecting

Symptoms: Claude doesn’t show your tools

Check:

Configuration file syntax is valid JSON
Paths are absolute and correct
MXCP is installed and in PATH
Project has valid mxcp-site.yml

Test manually:

cd /path/to/project
mxcp serve --transport stdio

Type {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}} and press Enter.

Tool Calls Failing

Symptoms: Claude reports errors when using tools

Check:

Run mxcp validate in your project
Run mxcp test to verify functionality
Check Claude’s developer console for errors

Permission Errors

Symptoms: “Permission denied” or similar errors

Check:

Virtual environment activation
File permissions on project directory
Database connection permissions

Slow Response Times

Symptoms: Tools take long to respond

Optimize:

Check database query performance
Enable caching where appropriate
Use materialized views for complex queries

Developer Console

Access Claude Desktop’s developer console:

macOS: Cmd + Option + Shift + I
Windows/Linux: Ctrl + Shift + Alt + I

Look for:

Connection errors
Request/response timing
Error messages

Log Files

Check MCP server logs for detailed error information:

macOS: ~/Library/Logs/Claude/mcp*.log
Windows: %APPDATA%\Claude\logs\mcp*.log

Windows-Specific Issues

If you see ENOENT errors referencing ${APPDATA}, add the expanded path to the env key:

{
  "mcpServers": {
    "my-project": {
      "command": "mxcp",
      "args": ["serve", "--transport", "stdio"],
      "cwd": "C:\\path\\to\\project",
      "env": {
        "APPDATA": "C:\\Users\\YourUsername\\AppData\\Roaming"
      }
    }
  }
}

Best Practices

1. Use Descriptive Server Names

{
  "mcpServers": {
    "sales-analytics": { ... },
    "customer-support-tools": { ... }
  }
}

2. Test Before Connecting

Always verify your MXCP project works:

cd /path/to/project
mxcp validate
mxcp test
mxcp serve --transport stdio

3. Start Simple

Begin with a single tool to verify the connection:

mxcp: 1
tool:
  name: hello
  description: Test tool that says hello
  return:
    type: string
  source:
    code: "SELECT 'Hello from MXCP!'"
  tests:
    - name: test_hello
      result: "Hello from MXCP!"

4. Monitor Logs

Keep an eye on logs during development:

{
  "mcpServers": {
    "my-project": {
      "command": "mxcp",
      "args": ["serve", "--transport", "stdio", "--log-level", "INFO"],
      "cwd": "/path/to/project"
    }
  }
}

5. Use Profiles for Environments

{
  "mcpServers": {
    "dev-server": {
      "command": "mxcp",
      "args": ["serve", "--transport", "stdio", "--profile", "dev"],
      "cwd": "/path/to/project"
    },
    "prod-server": {
      "command": "mxcp",
      "args": ["serve", "--transport", "stdio", "--profile", "prod"],
      "cwd": "/path/to/project"
    }
  }
}

Example Configuration

Complete example with multiple projects:

{
  "mcpServers": {
    "sales-data": {
      "command": "/home/user/.venv/bin/mxcp",
      "args": [
        "serve",
        "--transport", "stdio",
        "--profile", "production",
        "--log-level", "INFO"
      ],
      "cwd": "/home/user/projects/sales-mcp",
      "env": {
        "WAREHOUSE_HOST": "analytics.company.com"
      }
    },
    "support-tools": {
      "command": "mxcp",
      "args": ["serve", "--transport", "stdio"],
      "cwd": "/home/user/projects/support-mcp"
    }
  }
}

Next Steps

dbt Integration - Data transformation
DuckDB Integration - SQL engine
Operations - Production deployment