Skip to content
MXCP
Star -

Common Tasks

Quick answers to “How do I…?” questions. Each task links to full documentation.

Getting Started

Section titled “Getting Started”

How do I create a new project?

Section titled “How do I create a new project?”
Terminal window
mkdir my-project && cd my-project
mxcp init --bootstrap  # Creates example endpoint

Full guide →

How do I run my first tool?

Section titled “How do I run my first tool?”
Terminal window
mxcp run tool hello_world --param name=Alice

Hello World tutorial →

How do I connect to Claude Desktop?

Section titled “How do I connect to Claude Desktop?”

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Full guide →

Creating Endpoints

Section titled “Creating Endpoints”

How do I create a SQL tool?

Section titled “How do I create a SQL tool?”
tools/my-tool.yml
mxcp: 1
tool:
  name: my_tool
  description: What this tool does
  parameters:
    - name: param_name
      type: string
      description: Parameter description
  return:
    type: object
  source:
    file: ../sql/my-tool.sql

SQL endpoints tutorial →

How do I create a Python tool?

Section titled “How do I create a Python tool?”
tools/my-tool.yml
mxcp: 1
tool:
  name: my_tool
  description: What this tool does
  language: python
  parameters:
    - name: param_name
      type: string
      description: Parameter description
  return:
    type: object
  source:
    file: ../python/my_module.py
python/my_module.py
from mxcp.runtime import db


def my_tool(param_name: str) -> dict:
    results = db.execute("SELECT * FROM data WHERE name = $name", {"name": param_name})
    return {"data": results}

Python endpoints tutorial →

How do I create a resource?

Section titled “How do I create a resource?”
resources/user.yml
mxcp: 1
resource:
  uri: users://{id}
  description: Get user by ID
  parameters:
    - name: id
      type: integer
      description: User ID
  return:
    type: object
  source:
    code: "SELECT * FROM users WHERE id = $id"

Endpoints concept →

Security

Section titled “Security”

How do I add authentication?

Section titled “How do I add authentication?”

Add to ~/.mxcp/config.yml:

projects:
  my-project:
    profiles:
      default:
        auth:
          provider: github
          github:
            client_id: your_client_id
            client_secret: your_client_secret

Authentication guide →

How do I restrict access to a tool?

Section titled “How do I restrict access to a tool?”

Add input policy:

policies:
  input:
    - condition: "user.role != 'admin'"
      action: deny
      reason: "Admin access required"

Policies guide →

How do I filter sensitive data?

Section titled “How do I filter sensitive data?”

Add output policy:

policies:
  output:
    - condition: "user.role != 'admin'"
      action: filter_fields
      fields: ["salary", "ssn"]
      reason: "Restricted to admins"

Or mark fields as sensitive:

return:
  type: object
  properties:
    ssn:
      type: string
      sensitive: true

Policies guide →

How do I enable audit logging?

Section titled “How do I enable audit logging?”

Add to mxcp-site.yml:

profiles:
  default:
    audit:
      enabled: true
      path: audit/logs.jsonl

Query logs:

Terminal window
mxcp log --since 1h
mxcp log --tool my_tool --status error

Auditing guide →

Testing & Quality

Section titled “Testing & Quality”

How do I add tests to an endpoint?

Section titled “How do I add tests to an endpoint?”

Add tests section to your endpoint YAML:

tests:
  - name: basic_test
    arguments:
      - key: param_name
        value: "test_value"
    result_contains:
      expected_field: "expected_value"

Run tests:

Terminal window
mxcp test

Testing guide →

How do I test with different user roles?

Section titled “How do I test with different user roles?”
Terminal window
mxcp run tool my_tool \
  --param id=123 \
  --user-context '{"role": "admin", "permissions": ["read", "write"]}'

Or in YAML tests:

tests:
  - name: admin_access
    user_context:
      role: admin
    arguments:
      - key: id
        value: 123

Policies guide →

How do I validate my endpoints?

Section titled “How do I validate my endpoints?”
Terminal window
mxcp validate                        # All endpoints
mxcp validate tools/my_tool.yml      # Specific endpoint
mxcp validate --debug                # Detailed output

Validation guide →

How do I check for linting issues?

Section titled “How do I check for linting issues?”
Terminal window
mxcp lint

Linting guide →

Configuration

Section titled “Configuration”

How do I use environment-specific settings?

Section titled “How do I use environment-specific settings?”

Define profiles in mxcp-site.yml:

profiles:
  development:
    duckdb:
      path: dev.db
    audit:
      enabled: false


  production:
    duckdb:
      path: /data/prod.db
    audit:
      enabled: true

Use profile:

Terminal window
mxcp serve --profile production
# or
export MXCP_PROFILE=production

Configuration guide →

How do I use secrets?

Section titled “How do I use secrets?”

Add to ~/.mxcp/config.yml:

projects:
  my-project:
    profiles:
      default:
        secrets:
          - name: api_key
            type: custom
            parameters:
              value: "secret-value"

Access in Python:

from mxcp.runtime import config
secret = config.get_secret("api_key")
api_key = secret["value"] if secret else None

Configuration guide →

How do I use Vault for secrets?

Section titled “How do I use Vault for secrets?”
~/.mxcp/config.yml
vault:
  enabled: true
  address: https://vault.example.com
  token_env: VAULT_TOKEN


projects:
  my-project:
    profiles:
      default:
        secrets:
          - name: db_password
            parameters:
              password: "vault://secret/database#password"

Configuration guide →

Operations

Section titled “Operations”

How do I deploy to production?

Section titled “How do I deploy to production?”

With Docker:

FROM python:3.11-slim
RUN pip install mxcp
COPY . /app
WORKDIR /app
CMD ["mxcp", "serve", "--transport", "streamable-http", "--port", "8000"]

Deployment guide →

How do I enable monitoring?

Section titled “How do I enable monitoring?”

Set OpenTelemetry environment variables:

Terminal window
export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318
export OTEL_SERVICE_NAME=mxcp-prod
export MXCP_TELEMETRY_ENABLED=true

Monitoring guide →

How do I reload configuration without restart?

Section titled “How do I reload configuration without restart?”
Terminal window
# Send SIGHUP
kill -HUP $(pgrep -f "mxcp serve")


# Or use admin socket
curl --unix-socket /run/mxcp/mxcp.sock -X POST http://localhost/reload

Admin socket guide →

How do I check for drift?

Section titled “How do I check for drift?”
Terminal window
# Create baseline
mxcp drift-snapshot


# Check for changes
mxcp drift-check

Drift detection guide →

Database

Section titled “Database”

How do I access the database from Python?

Section titled “How do I access the database from Python?”
from mxcp.runtime import db


# Execute query
results = db.execute(
    "SELECT * FROM users WHERE id = $id",
    {"id": 123}
)


# results is a list of dicts
for row in results:
    print(row["name"])

Python reference →

How do I use DuckDB extensions?

Section titled “How do I use DuckDB extensions?”

Add to mxcp-site.yml:

extensions:
  - httpfs
  - parquet
  - name: h3
    repo: community

DuckDB integration →

How do I integrate with dbt?

Section titled “How do I integrate with dbt?”

Enable in mxcp-site.yml:

dbt:
  enabled: true
  model_paths: ["models"]

Run dbt through MXCP:

Terminal window
mxcp dbt run

dbt integration →

Troubleshooting

Section titled “Troubleshooting”

Tool not found

Section titled “Tool not found”
Terminal window
mxcp list  # See available endpoints

Check that:

  • File is in tools/ directory
  • enabled: true is set
  • YAML is valid (mxcp validate)

Validation errors

Section titled “Validation errors”
Terminal window
mxcp validate --debug

Check YAML indentation and required fields.

Policy denials

Section titled “Policy denials”
Terminal window
mxcp run tool my_tool --user-context '{"role": "admin"}' --debug

Check policy conditions match user context.

Python import errors

Section titled “Python import errors”
Terminal window
# Ensure virtual environment
source .venv/bin/activate


# Debug
mxcp run tool my_tool --debug

Quickstart →