Menu

Troubleshooting with Doctor

Diagnose paso MCP server setup issues with usepaso doctor.

Why is my MCP server not working?

Run usepaso doctor. It checks your setup end-to-end and tells you exactly what’s wrong. Five checks, one command.

Run Doctor

usepaso doctor
usepaso doctor

  ok   usepaso.yaml found
  ok   YAML parses correctly
  ok   Validation passes (6 capabilities)
  ok   USEPASO_AUTH_TOKEN set
  ok   Base URL reachable (https://sentry.io/api/0, 187ms)

────────────────────────────────────
All checks passed.

What Doctor Checks

1. File Exists

Verifies that usepaso.yaml exists at the expected path.

If it fails:

  FAIL usepaso.yaml found
  │    Run usepaso init to create one.

Fix: Run usepaso init to create a declaration, or use -f to point to the right file:

usepaso doctor -f ./path/to/usepaso.yaml

2. YAML Parses

Checks that the file is valid YAML.

If it fails:

  FAIL YAML parses correctly
  │    Unexpected token at line 12

Fix: Check for syntax errors like incorrect indentation, missing colons, or unquoted special characters.

3. Validation Passes

Runs the full spec validation. Reports the number of capabilities and any warnings.

If it fails:

  FAIL Validation passes
  │    3 error(s). Run usepaso validate for details.

Fix: Run usepaso validate to see the specific errors. Common issues:

  • Missing required fields (name, description, base_url)
  • Path parameters without matching inputs
  • Duplicate capability names

4. Auth Token

Checks whether USEPASO_AUTH_TOKEN is set when your declaration configures authentication.

If it fails:

  FAIL USEPASO_AUTH_TOKEN set
  │    Set it with: export USEPASO_AUTH_TOKEN=your-token

Fix:

export USEPASO_AUTH_TOKEN="your-api-token"

If your auth type is none, this check passes automatically (no token needed).

An empty token also fails:

  FAIL USEPASO_AUTH_TOKEN set
  │    Token is empty. Set a valid token.

5. Base URL Reachable

Makes a HEAD request to service.base_url to verify connectivity. Times out after 5 seconds.

If it fails:

  FAIL Base URL reachable
  │    Could not reach https://api.example.com. Check the URL and your network.

Fix:

  • Verify the URL is correct (check for typos, missing path prefix)
  • Check your network connection
  • If behind a VPN or firewall, ensure the API is reachable

When to Run Doctor

Run usepaso doctor when:

  • Setting up a new declaration for the first time
  • Your MCP server fails to start
  • Claude Desktop or Cursor can’t connect
  • You’re getting 401 errors and aren’t sure why
  • After changing your declaration or auth configuration

Quick Checklist

If doctor reports failures, fix them in order. Each check depends on the previous ones:

  1. File exists? If not, usepaso init.
  2. YAML parses? If not, fix syntax.
  3. Validation passes? If not, usepaso validate for details.
  4. Token set? If not, export USEPASO_AUTH_TOKEN=...
  5. URL reachable? If not, check the URL and network.

Your setup is diagnosed.

Doctor tells you exactly what’s wrong and how to fix it.

Next, you might want to: