Five Ways to Test Before You Ship

Tutorials 5h1vmani 2 min
On this page

You’ve written a usepaso.yaml. Before you connect it to Claude, here are five ways to verify everything works.

1. Validate

The baseline. Checks your declaration against the spec.

usepaso validate
valid (GitHub, 4 capabilities, 0 regrets)

This catches structural issues: missing required fields, invalid URLs, path parameters without matching inputs, duplicate capability names. If validate passes, your YAML is well-formed.

2. Validate with —strict

Goes beyond structure. Checks for best practices.

usepaso validate --strict

Strict mode flags:

  • DELETE capabilities without consent_required. Agents could delete data without asking.
  • Descriptions shorter than 10 characters. Agents need clear descriptions to choose the right tool.
  • Write/admin capabilities with no constraints. Consider adding rate limits.
  • No permissions section. All capabilities are accessible by default.

These aren’t errors. They’re warnings about things you probably want to fix before production.

3. Inspect

See exactly what MCP tools your declaration produces.

usepaso inspect
Service: GitHub
Tools:   4
Auth:    bearer

  ┌ list_repos (read)
  │ GET /users/{username}/repos
  │ List repositories for a user
  │ params: username*: string, sort: enum, per_page: integer
  │
  ├ list_issues (read)
  │ GET /repos/{owner}/{repo}/issues
  │ List issues in a repository
  │ params: owner*: string, repo*: string, state: enum
  │
  ├ create_issue (write) [consent required]
  │ POST /repos/{owner}/{repo}/issues
  │ Create an issue in a repository
  │ params: owner*: string, repo*: string, title*: string, body: string
  │
  └ close_issue (write) [consent required]
    PATCH /repos/{owner}/{repo}/issues/{issue_number}
    Close an issue
    params: owner*: string, repo*: string, issue_number*: integer, state*: enum

This is what agents see. Check that descriptions are clear, permissions are correct, and forbidden capabilities are excluded.

Use usepaso inspect --json for machine-readable output if you’re building automation around it.

4. Dry run

Preview the exact HTTP request paso would send, without sending it.

usepaso test list_repos \
  -p username=octocat \
  --dry-run
--- DRY RUN (no request will be made) ---

GET https://api.github.com/users/octocat/repos
Authorization: Bearer ...

This verifies URL construction, parameter placement (path vs. query vs. body), and auth headers. No API calls. No side effects.

To verify all capabilities at once:

usepaso test --all --dry-run
ok list_repos     GET https://api.github.com/users/{username}/repos
ok list_issues    GET https://api.github.com/repos/{owner}/{repo}/issues
ok create_issue   POST https://api.github.com/repos/{owner}/{repo}/issues
ok close_issue    PATCH https://api.github.com/repos/{owner}/{repo}/issues/{issue_number}

4 passed. 4 capabilities total.

If any capability fails to build a valid request, you’ll see it here.

5. Doctor

The end-to-end check. Verifies your entire setup.

usepaso doctor
usepaso doctor

  ok   usepaso.yaml found
  ok   YAML parses correctly
  ok   Validation passes (4 capabilities)
  ok   USEPASO_AUTH_TOKEN set
  ok   Base URL reachable (https://api.github.com, 87ms)

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

Doctor checks five things in sequence: file exists, YAML parses, validation passes, auth token is set, and the base URL is reachable. If anything fails, it tells you exactly what’s wrong and how to fix it.

Run doctor before connecting to an MCP client. If doctor passes, you’re ready.

The sequence

For a new declaration:

usepaso validate --strict    # Structure + best practices
usepaso inspect              # Review what agents will see
usepaso test --all --dry-run # Verify all requests build correctly
usepaso doctor               # End-to-end setup check
usepaso serve                # Ship it

Five checks, then serve. No surprises.

Questions

Can I add these checks to CI? Yes. usepaso validate --strict --json returns structured output with a non-zero exit code on failure. Add it to your CI pipeline the same way you’d add a linter.

What if doctor says the base URL is unreachable? Check the base_url in your YAML. It needs to be the root URL of your API, not a specific endpoint. Doctor sends a HEAD request to verify it responds.

Does dry run check auth tokens? Dry run verifies the token is set and shows the header format, but it does not make a real request. Use usepaso test list_repos (without --dry-run) to send a live request and verify auth works end-to-end.

Related:

Read the full CLI reference.