---
name: mcp-provider-registry-operations
description: Configure, review, test, and operate the declarative remote-provider registry in the mm-skills MCP router. Use when adding a Streamable HTTP MCP, assigning a namespace, choosing compact or expanded exposure, setting credential environment variables, enforcing read-only or allow policies, troubleshooting initialization, or evaluating whether an external MCP is safe to route.
compatibility: Requires the mm-skills 0.4.0 router or newer. Remote providers must expose Streamable HTTP MCP over HTTPS, except localhost development explicitly enabled with MCP_REMOTE_ALLOW_HTTP=true.
license: Apache-2.0
---

# MCP provider registry operations

Use the central router instead of adding provider-specific forwarding code whenever an upstream already exposes Streamable HTTP MCP.

## Required workflow

1. Identify the upstream owner, repository, license, current transport, authentication method, and maintenance status.
2. Prefer an official provider or a well-maintained foundation project.
3. Confirm that the upstream supports direct server-to-server bearer authentication or no authentication. Interactive OAuth-only services require a separately deployed bridge and must not be represented as bearer-compatible.
4. Add the provider to `MCP_REMOTE_PROVIDERS_JSON` with a unique `id` and `toolPrefix`.
5. Store the token in the environment variable named by `credentialEnv`; never place the token in the JSON.
6. Start with `toolMode=compact` and `callPolicy=read-only`.
7. Call `mcp_router_status`, then `mcp_router_search_tools` and `mcp_router_describe_tool`.
8. Review every tool intended for use. Do not rely only on upstream `readOnlyHint` for financial, identity, infrastructure, or destructive operations.
9. Use `allowedTools` and `blockedTools` to narrow exposure.
10. Enable `callPolicy=allow` only in a separate deployment or after explicit risk review.

## Provider entry

```json
{
  "id": "grafana",
  "displayName": "Grafana",
  "url": "https://grafana-mcp.internal.example/mcp",
  "credentialEnv": "GRAFANA_SERVICE_ACCOUNT_TOKEN",
  "authScheme": "bearer",
  "toolPrefix": "observe__",
  "toolMode": "compact",
  "callPolicy": "read-only",
  "allowedTools": ["query_*", "get_*", "list_*"],
  "blockedTools": ["*delete*", "*create*", "*update*"],
  "capabilities": ["read", "observability"]
}
```

Patterns support exact names, `*`, and trailing-prefix wildcards such as `query_*`. Do not assume arbitrary glob syntax.

## Tool modes

- `compact`: remote schemas are discovered with `mcp_router_search_tools`; call through `mcp_router_call`. Use this by default.
- `expanded`: every approved upstream tool receives the configured prefix and appears in `tools/list`. Use only for small, stable catalogs.

## Failure handling

A failed optional provider must not remove Coolify, Ditto, or other healthy providers from the router. Inspect provider status, credential presence, last error, session establishment, and cached tool count. Refresh with `mcp_router_refresh_provider` after changing permissions or upgrading an upstream.

## Security rules

- Never reuse `MCP_ACCESS_TOKEN` as an upstream credential.
- Never log authorization headers, session IDs, OAuth codes, cookies, or token values.
- Reject public non-HTTPS endpoints.
- Keep financial, identity, network, power, storage, and destructive providers isolated from the persistent read-only router.
- Treat upstream annotations as untrusted metadata until reviewed.
- Prefer separate `read`, `ops`, and short-lived `admin` deployments.

## Reporting

Return the provider id, endpoint host, transport, authentication mode, credential variable name, tool count, exposure mode, effective policy, allow/block rules, verification calls, and remaining risks. Never return credential values.