Register an MCP server

Registering a server makes a private MCP server known to the gateway so it can be approved, policy‑governed, and routed to. Registration does not expose anything on its own — an approved policy still decides who may discover or call its tools.

Requires mcp_server.register

You need the mcp_server.register permission in the target environment. Check yours on Authenticate to the gateway.

1. Validate the manifest to catch schema and policy‑reference errors before submitting.
2. Submit it to the registry, which creates an immutable submission for review.
3. Approve it (a reviewer with the right permission) — covered under Approvals.

1 · Validate the manifest

Validate an MCP server manifest

UIAPICLI

1. Open Govern → MCP servers → Register.
2. Paste or upload your manifest and click Validate — errors are listed inline with the offending field.

POST/v1/registry/validate-manifest

Copy

curl -X POST "$GATEWAY/v1/registry/validate-manifest" \
-H "authorization: Bearer $TOKEN" \
-H "content-type: application/json" \
--data @manifest.json

View validateRegistryManifest in the API reference →

Copy

gatewayctl validate-manifest manifest.yaml

Every gatewayctl verb accepts --format text|json.

Note

Semantic failures (including policy‑ref errors) return 200 with valid: false and an errors[] array — they are validation results, not request errors.

2 · Submit it to the registry

Submit the server for approval

UIAPICLI

1. After a clean validation, click Register.
2. The server appears in Govern → MCP servers with status submitted, awaiting review.

POST/v1/mcp-servers

Copy

curl -X POST "$GATEWAY/v1/mcp-servers" \
-H "authorization: Bearer $TOKEN" \
-H "content-type: application/json" \
--data @manifest.json

View registerMcpServer in the API reference →

Copy

gatewayctl register-server manifest.yaml --format json

Every gatewayctl verb accepts --format text|json.

Probe a remote server first

Not sure what tools a remote server exposes? POST /v1/registry/probe-mcp-server performs an MCP initialize + tools/list from the backend and returns the discovered tools for review — without registering or approving anything.

Next

Once submitted, a reviewer approves it (Approvals), after which it is projected to the data plane and becomes callable per policy. Verify the loop with your first governed tool call.