Common MCP Server Errors (and How to Fix Them)

Tutorials 5h1vmani 2 min
On this page

You wrote a usepaso.yaml. You ran usepaso validate. Something failed. Here are the seven errors you’re most likely to see, what causes them, and how to fix each one.

1. Path parameter not found in inputs

capabilities[0].path: path parameter "{item_id}" not found in inputs

Your path has a {param} placeholder but no matching input with in: path.

Before:

- name: get_item
  description: Get an item by ID
  method: GET
  path: /items/{item_id}
  permission: read
  inputs:
    query:
      type: string
      description: Search query
      in: query

Fix: Add the path parameter to inputs.

  inputs:
    item_id:
      type: string
      required: true
      description: The item ID
      in: path

Every {param} in the path needs a matching input with in: path and required: true.

2. Duplicate capability name

capabilities[1].name: duplicate capability name "list_items"

Two capabilities share the same name field. Each name must be unique within a declaration.

Fix: Rename one of them.

- name: list_items
  description: List all items
  # ...

- name: list_archived_items
  description: List archived items
  # ...

3. Enum without values

capabilities[0].inputs.status: enum type must have values defined

You declared an input as type: enum but didn’t provide the allowed values.

Before:

inputs:
  status:
    type: enum
    description: Filter by status
    in: query

Fix: Add the values array.

inputs:
  status:
    type: enum
    values: [active, archived, deleted]
    description: Filter by status
    in: query

4. Invalid base URL

service.base_url: service.base_url must be a valid URL

The base_url must be a full URL with protocol. Not a domain, not a relative path.

Before:

service:
  base_url: api.example.com/v1

Fix: Include the protocol.

service:
  base_url: https://api.example.com/v1

5. Non-snake_case capability name

capabilities[0].name: "listItems" must be snake_case

Capability names must be snake_case. MCP tool names follow this convention.

Before:

- name: listItems

Fix:

- name: list_items

The same rule applies to getUser → get_user, createPaymentIntent → create_payment_intent.

6. Permission references unknown capability

permissions.read: references unknown capability "nonexistent_capability"

Your permissions object references a capability name that doesn’t exist in capabilities.

Before:

capabilities:
  - name: list_items
    # ...

permissions:
  read:
    - list_items
    - get_item_details

Fix: Either add the missing capability or remove the reference. Every name in permissions must match a declared capability.

7. Missing required fields

service.description: service.description is required

The service object requires both name and description. Agents read the description to understand what the API does.

Fix:

service:
  name: Inventory
  description: Product inventory and stock management for e-commerce
  base_url: https://api.inventory.com/v1

Write descriptions that help agents decide whether to use this service. “API” is not a description.

Before you debug: run doctor

If your YAML validates but the server won’t connect, run usepaso doctor.

usepaso doctor
usepaso doctor

  ok   usepaso.yaml found
  ok   YAML parses correctly
  ok   Validation passes
  FAIL USEPASO_AUTH_TOKEN set
  │    Set it with: export USEPASO_AUTH_TOKEN=your-token
  FAIL Base URL reachable
  │    Could not reach https://api.example.com. Check the URL and your network.

Doctor checks five things in order: file exists, YAML parses, validation passes, auth token is set, base URL is reachable. It tells you exactly what failed and how to fix it.

The fix sequence

When something breaks, work through this:

usepaso validate          # Structural errors
usepaso validate --strict # Best-practice warnings
usepaso doctor            # Environment + connectivity
usepaso test --all --dry-run  # Request construction

Fix errors in that order. Structural issues first, environment second, request shape last.

Questions

What does “0 regrets” mean in the validation output? It’s paso’s way of saying no warnings. valid (Sentry, 6 capabilities, 0 regrets) means the declaration is clean. Regrets appear when --strict finds best-practice issues like missing consent gates on DELETE operations.

Can I validate without installing paso globally? Yes. npx usepaso validate works without a global install. Same for every other command.

Does validate check if the API actually works? No. Validate only checks the YAML structure. Use usepaso doctor to verify the base URL is reachable and the auth token is set, or usepaso test to send a real request.

Related:

Read the full CLI reference.