Connect an MCP server

An MCP server is the system that actually carries out your agents' tool calls: a refund service, a CRM, a deployment tool. K-Block sits in front of it. Agents never call the server directly; they call the Gateway, which decides each call and, when it is allowed or approved, forwards it to the server you registered.

Registering a server tells K-Block where to send calls and which credential to send with them. It does not make any tool callable yet: after registering, you discover the server's tools and expose the ones agents may use. For the concepts, see Tools and MCP servers.

Before you start

• Role. Owners, admins and developers can register servers and run discovery. Approvers and viewers can only view them. See Roles and permissions.
• Transport. K-Block connects to MCP servers over Streamable HTTP. The server needs an HTTP endpoint, for example https://tools.example.com/mcp.
• Reachability. Both the Cloud API (for discovery) and the Gateway (for every executed call) must be able to reach the URL. The server needs a public https address; see Private upstreams.
• Credential. If the server requires authentication, have the complete Authorization header value ready, for example Bearer <token>.

Register the server

1. Open the registration form

   In the dashboard, open Tools & MCP servers and select Register MCP server.

2. Fill in the fields

   Field	What to enter
   Name	A name people recognize, up to 200 characters, unique in the organization (409 NAME_TAKEN otherwise). Shown to approvers next to the URL.
   URL	The server's MCP endpoint. See URL rules.
   Authorization header (optional)	The complete header value the server expects, such as Bearer <token>. See The credential.
   Server KID (optional)	Only for K-Block-aware servers. Leave it empty for an ordinary MCP server. See K-Block-aware servers.

3. Register

   Select Register server. The dashboard opens the server's page, where you discover its tools.

The number of servers per organization depends on your plan. Over the limit, registration fails with 402 PLAN_LIMIT_EXCEEDED; see Billing.

URL rules

The Cloud API checks the URL when you register or change it, and the Gateway checks it again every time it connects:

• It must be https. Plain http is refused.
• It must not contain a user name or password. Put credentials in the authorization header.
• It must not contain a query (?…) or a fragment (#…). The URL is signed into the evidence of every call, and so into every receipt, which cannot be redacted later. Tokens belong in the authorization header.
• Its host name is resolved and every address is checked. Private, loopback, link-local and cloud metadata addresses are refused. A host name that does not resolve is refused too.
• At most 2,048 characters.

A refused URL returns 422 URL_NOT_ALLOWED; details.reason names the rule, for example URL_QUERY_NOT_ALLOWED.

Private upstreams

K-Block only connects to public https addresses. A URL whose host is, or resolves to, a private, loopback or other internal address is refused when you register it (422 URL_NOT_ALLOWED). A server that is reachable only on a private network cannot be used: give your MCP server a public https address before you register it.

The address is checked again every time K-Block connects. If a server you registered later fails with 422 UPSTREAM_REFUSED in discovery or UPSTREAM_BLOCKED at call time, K-Block refused its address before connecting, for example because its host name now resolves to a private address. Nothing was sent to the server. Make sure the host name resolves only to public addresses.

The credential

The Authorization header is the credential the upstream server expects. Enter the whole header value exactly as the server wants it (for example Bearer <token>), 1 to 4,096 visible ASCII characters.

• It is stored encrypted, bound to this server, and is never shown again. The server page only says stored (encrypted) or none.
• Discovery and the Gateway send it unchanged as the Authorization header to this server's URL.
• It is tied to the server's origin (scheme, host and port). If you move a server that has a stored header to another origin, you must enter the header again in the same save (the new value, or remove it). Otherwise the save fails with 400 VALIDATION_FAILED (issue AUTH_HEADER_REQUIRED). This stops anyone who can edit the URL from sending your credential to a host of their choice.
• If the upstream echoes the header back in an error message, the Gateway removes it before recording or showing the error.

To rotate the credential, open the server, enter the new value in New authorization header (optional), and select Save server. To remove it, tick Remove the stored authorization header.

K-Block-aware servers (server KID)

Most MCP servers are ordinary servers: the Gateway is the last component that checks K-Block evidence, and the server page shows K-Block-aware: No.

A K-Block-aware server verifies the evidence of each call itself and returns a signed attestation of what it did. To register one, enter its Server KID (a key ID of the form kid:kb: followed by 52 characters). The KID must belong to a valid service identity. If K-Block does not know the identity yet, paste its public identity documents (a JSON array) into Server identity documents.

For a K-Block-aware server, the Gateway sends the evidence with each call and requires a valid attestation in the answer; without one the call is recorded as failed (ATTESTATION_MISSING or ATTESTATION_INVALID). If the server refuses the evidence, the call is recorded as failed with UPSTREAM_REFUSED. See Identities and KIDs and What a receipt proves.

Discover tools

Discovery asks the server which tools it offers.

1. Open the server's page (from Tools & MCP servers, under MCP servers).
2. In Discover tools, select Discover tools.

The Cloud API connects to the server with the stored credential, runs a real MCP initialize and tools/list, and shows each tool's name, title, description and input schema. Nothing is cached or invented: what you see is what the server answered. A tool that is already exposed shows exposed as with its exposed name. Select Discover again after the server changes. Discovering again does not update tools you already exposed: each keeps the input schema it was exposed with (see Expose and map tools).

Discovery exposes nothing. Agents see a tool only after you expose it, enable it and grant its action in a delegation. Continue with Expose and map tools.

Discovery reads at most 20 pages of tools/list, at most 2,000 tools and 8 MiB of answers in total, and gives up after about 15 seconds.

Discovery errors

If discovery fails, the server page shows Discovery failed with the reason.

An empty result ("The upstream reports no tools") means the server answered tools/list with no tools. Check the server's configuration.

Upstream failures at call time

Once tools are exposed, the Gateway connects to the server for every executed call. It sends each call at most once and never retries it, so a failure is recorded, not repeated. The agent gets upstream_error with one of these codes:

Problems the Gateway finds before it starts executing (most UPSTREAM_BLOCKED cases and UPSTREAM_CREDENTIAL_INVALID) refuse the call without using up its approval, so the agent can retry once the problem is fixed. Failures after the Gateway started executing are recorded on the action as failed, with a signed receipt, and use up the approval.

When a failure happened after the request was sent (a timeout, a lost connection, an HTTP 5xx), the detail says the request was sent but no valid answer was received: the server may have acted. Check the effect in the upstream system before the agent repeats the call.

For more, see Gateway and tools troubleshooting and Execution and results.

Change, disable or delete a server

On the server's page:

• Server settings changes the name, the Status (Active, or Disabled (its tools are not callable)), the URL, the server KID and the credential. Select Save server.
• While the server has enabled tools, only an owner or admin can change its URL, server KID or credential; a developer gets 403 ADMIN_REQUIRED. A developer can disable the server or its tools at any time.
• Any change of the URL, server KID or credential, by anyone, makes the server's enabled tools stale until an owner or admin re-authorizes them. The page warns you before you save (Its tools will need re-authorization).
• Delete this server deletes the server and its exposed tools. Once any of its tools has recorded actions, deleting fails with 409 IN_USE; disable the server instead.

Next steps