MCP CLI

Output is JSON by default; pass --output human for tables and one-line summaries:

provon mcp --output human servers list

Prerequisites#

• Selected project and authenticated credential.
• Management commands (servers, credentials, tools, policies) require mcp:manage; neither capability is in the default key set, so grant it explicitly.
• Tool invocation through the gateway requires mcp:invoke; see MCP Security.

Command Tree#

provon mcp
  servers list
  servers create <display-name> [flags]
  servers update <server-id> [flags]
  servers delete <server-id>
  servers test <server-id>
  servers discover <server-id>
  servers sync <server-id>
  servers credentials list <server-id>
  servers credentials add <server-id> [flags]
  servers credentials test <server-id> <credential-id>
  servers credentials promote <server-id> <credential-id>
  servers credentials pause <server-id> <credential-id>
  servers credentials resume <server-id> <credential-id>
  servers credentials delete <server-id> <credential-id>
  openapi import [display-name] --spec-file <path> | --url <url>
  tools list <server-id>
  tools set-publish-state <server-id> <tool-id> --state <state>
  policies list
  policies create [flags]
  policies delete <policy-id>

Servers#

# Register a remote MCP server over streamable HTTP
provon mcp servers create "Acme internal tools" --source mcp \
  --url https://mcp.acme.example.com

# List, update, disable, delete
provon mcp servers list
provon mcp servers update mcp_srv_xxx --url https://new-host.example.com
provon mcp servers update mcp_srv_xxx --disabled
provon mcp servers delete mcp_srv_xxx

Create flags: --source mcp|openapi (default mcp), --url, --spec-file <path>, --enabled (default) / --disabled. MCP servers require an HTTP --url; OpenAPI servers derive it from the spec document.

Update flags: --name, --url (pass an empty value to clear), --spec-file, --enabled / --disabled.

Test, Discover, And Sync#

provon mcp servers test mcp_srv_xxx      # upstream reachability
provon mcp servers discover mcp_srv_xxx # provisional tools without writing the catalog
provon mcp servers sync mcp_srv_xxx      # persist the upstream tool catalog

discover previews what sync would register; sync rebuilds the persisted tool catalog.

Credentials#

Credentials are sealed at rest and sent on the whitelisted outbound header for the server. New credentials start as backups; exactly one credential is the active primary used on the outbound path, and the rest are held for cutover after their own isolation test.

provon mcp servers credentials list mcp_srv_xxx
provon mcp servers credentials add mcp_srv_xxx \
  --label acme-robot --secret "<upstream token>" --auth-method authorization_bearer
provon mcp servers credentials test mcp_srv_xxx mcp_cred_yyy
provon mcp servers credentials promote mcp_srv_xxx mcp_cred_yyy
provon mcp servers credentials pause mcp_srv_xxx mcp_cred_yyy
provon mcp servers credentials resume mcp_srv_xxx mcp_cred_yyy
provon mcp servers credentials delete mcp_srv_xxx mcp_cred_yyy

add flags: --label (required), --secret (required), --auth-method (authorization_bearer, default; or x_api_key), --enabled / --disabled.

Behavior:

• test isolation-checks a credential without promoting it: 401 classifies as an invalid credential, 403 as permission denied (a policy problem rather than a bad secret), other responses as unreachable.
• promote atomically cuts the selected credential over to primary.
• pause / resume hold and re-enable a credential without revoking it.
• delete removes the credential permanently.

OpenAPI Import#

provon mcp openapi import "Acme CRM" --spec-file ./acme-openapi.json
provon mcp openapi import "Acme CRM" --url https://acme.example.com/openapi.json

Provide exactly one of --spec-file or --url (mcp.openapi_source_required otherwise). Import creates an openapi-source server and one draft tool per operation. Imported tools are not discoverable until published with tools set-publish-state; see OpenAPI import.

Tools#

provon mcp tools list mcp_srv_xxx
provon mcp tools set-publish-state mcp_srv_xxx mcp_tool_zzz --state draft

Publish states: draft, published, deprecated, archived.

Policies#

provon mcp policies list
provon mcp policies create \
  --effect allow \
  --principal-kind api_key --principal-ref "<invoking key id>" \
  --action read --action invoke \
  --priority 100
provon mcp policies delete mcp_pol_www

• --effect: allow or deny (required).
• --principal-kind: user or api_key (required); --principal-ref is required.
• --action: repeatable; at least one of read, invoke (mcp.policy_no_actions otherwise).
• Scope with repeatable --server <id> and --tool <name>; omit both for all targets.
• --priority defaults to 100; higher values order matches, and any deny overrides allow.

There is no manage action: mutating the catalog and policies requires the management-surface capability mcp:manage, not a principal-grantable tool action.

Two built-in servers, provon and duckduckgo, expose five tools (search_traces, get_trace, list_findings, get_finding, web_search) and are always addressable without a federation policy. Policies govern federated servers: admit tool calls with an allow policy, or carve out explicit denies.

Invoking Through The Gateway#

The tool gateway endpoint is not a provon mcp subcommand. Connect an MCP client to it with an mcp:invoke-bearing key:

• Node runtime: POST /mcp/v1
• Worker runtime: POST /v1
• Target a server with the mcp query parameter, e.g. POST /mcp/v1?mcp=<serverId>; omitting the parameter returns a 400 asking for the mcp id. Use the id shown by provon mcp servers list.

Success Check#

provon mcp servers list
provon mcp tools list <server-id>

A healthy result lists the server and its cataloged tools; after sync, newly registered tools appear in tools list, and OpenAPI tools move to callable state only after provon mcp tools set-publish-state <server-id> <tool-id> --state published.

Troubleshooting#