docs: provider management API (v1.8.0) + MCP provider_* tools

[maia-cloud-agent]

Description

This PR updates the Mintlify documentation to document the provider-scoped management surface introduced by the v1.8.0 provider management API and its corresponding MCP provider_* tools. The change is documentation-only: it makes the new provider tools discoverable, clarifies when they are exposed, and documents their authorization, validation, and error behavior.

What changed

The provided patch modifies intro/mcp-server.mdx to document the provider MCP tool surface.

Adds a Provider tools section

A new section documents seven provider tools and maps each tool to its corresponding provider API endpoint:

MCP tool	Documented endpoint
provider_list_plans	GET /provider/plans
provider_get_plan_methods	GET /provider/plans/:planId/methods
provider_get_node_status	GET /provider/nodes/:nodeId/status
provider_upsert_plan_methods	POST /provider/plans/:planId/methods
provider_upsert_node	PUT /provider/nodes
provider_upsert_ws_node	PUT /provider/nodes/ws
provider_set_node_status	POST /provider/nodes/status

The section also documents the expected response shape for provider_get_node_status:

{ node_id, in_sync, status }

and the documented node status values:

• healthy
• disabled by provider
• provider-deleted

Clarifies provider tool activation

The docs now state that provider tools are exposed only when:

1. ROUTEMESH_MGMT_TOKEN is set, and
2. the token’s customer is linked to a provider.

This makes explicit that setting the management token alone is not sufficient; the token’s customer must have a provider relationship for the provider_* tools to appear.

Documents provider authentication and scoping

The new section explains that the provider tools authenticate using the same management token, sent in the X-Api-Key header, and that provider resources are scoped to the provider associated with that token.

It also documents the provider authorization semantics:

• If the token’s customer is not linked to a provider, the result is 403 provider not resolved.
• If the requested resource belongs to another provider, the result is 404, so resource existence is not leaked.

This gives MCP clients and provider operators a clear contract for expected failure modes.

Documents node screening behavior

The patch adds explicit guardrails for node upserts:

• HTTP nodes must use public http(s) endpoints.
• WebSocket nodes must use public wss:// endpoints.
• Loopback, private, and link-local addresses are rejected before persistence.
• WebSocket nodes must support eth_subscribe("newHeads"), with the server dialing to verify.

The docs also document the related error behavior:

• Failed mandatory screening returns 400.
• A URL owned by another provider returns 404.
• A URL already registered to a different plan of the same provider returns 409.

This clarifies the validation boundary for provider node registration and helps prevent accidental or unsafe endpoint configuration.

Updates token documentation

The ROUTEMESH_MGMT_TOKEN environment variable table row is updated to state that, when set, the MCP server exposes:

• customer tools, and
• provider tools when the token’s customer is provider-linked.

The token-scoping note is also updated. Previously it described customer management tokens as scoped only to customer management routes. The updated note says the token is scoped to:

• the account’s customer management routes, and
• provider routes when the token is provider-linked.

This is a meaningful clarification for least-privilege token usage and token revocation.

Functional impact

There are no runtime code changes in the provided diff. The functional impact is documentation clarity and operational safety:

• Provider operators can discover the new provider_* MCP tools.
• AI MCP clients can understand which tools are available under a provider-linked management token.
• Operators can configure the MCP server correctly by understanding the provider-linkage requirement.
• Clients can handle expected provider-specific error responses correctly.
• Node upsert constraints are documented, reducing the risk of misconfigured or unsafe endpoints.
• Token permission scope is clarified, which supports safer credential management.

Technical context and added clarity

Several details in the patch reinforce the intended provider management model:

• Provider tools are not simply an extension of customer tools; they are gated by a customer-to-provider relationship.
• The documentation ties each MCP tool directly to an API path, improving traceability between the MCP tool and the API reference.
• The provider error model is documented explicitly, including 403 for missing provider linkage and 404 for cross-provider resource access.
• Node registration is documented as a screened operation, not a blind upsert, with distinct validation failures for unsafe URLs, foreign-provider URLs, and duplicate URLs within the same provider.
• The token-scoping language broadens from customer-only routes to customer plus provider routes, which is relevant for permission review and token lifecycle management.

[kodus-routemesh-hosted]

Kody Review Complete

Great news! 🎉
No issues were found that match your current review configurations.

Keep up the excellent work! 🚀

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

• Validate Business Logic: Ask Kody to validate your code against business rules by adding a comment with the @kody -v business-logic command.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

​