Add and approve an MCP server

The gateway connects to an MCP server by its address and pulls its manifest from /.well-known/mcp-manifest. You add servers at runtime in the portal, and nothing restarts. A new server has no tools for anyone until you approve three things: its connection, its policies and each tool definition.

You need the group mcp-platform-admin. Before you start, add the system the server uses (see Add and manage systems) and have the server running (see Install MCP servers).

Add a server

1. Open Administration, Servers and select Add server.
2. Enter the Address of the MCP endpoint, for example https://<server-host>:8443/mcp. Any host with any HTTPS certificate works. The gateway takes the server identifier (mcp-<system>) and the system from the manifest.
3. Optionally enter the System. If you fill it in, the gateway refuses a server whose manifest claims another system. Fill it in when you can: without it, a server can claim a system whose users already hold credentials.
4. If the address starts with http://, select Allow plain HTTP. Use it only for a server in the same Docker network as the gateway: plain HTTP sends users’ credentials unencrypted. Without the option the gateway refuses an http address (plain_http_not_allowed).
5. Select Save. If the portal asks for it, confirm your identity at the identity provider and save again.

The gateway checks the address, reads the certificate with a TLS handshake, pulls the manifest and shows the server with the connection state Pending approval. It refuses an address that resolves to loopback, link-local, unspecified, multicast or cloud metadata addresses, now and before every connection. Private ranges are allowed. To refuse more ranges, set MCP_SERVER_REFUSED_ADDRESSES (see Configuration).

If the add fails, the portal shows the reason:

Reason	Meaning
address_refused	The host resolves to a refused range
plain_http_not_allowed	http address without Allow plain HTTP
tls_handshake_failed	No TLS handshake with the address
manifest_unreachable	No 200 from /.well-known/mcp-manifest
manifest_invalid	The manifest failed the checks of the gateway
system_mismatch	The manifest claims another system than the one you entered
system_reserved	The system of the manifest is a reserved identifier
namespace_conflict	Another server already owns the namespace of its policies

Servers list

The Connection column shows the state of the link to the server:

State	Meaning	What to do
Pending approval	The connection was never approved. Its tools are hidden whatever else is approved	Approve the connection (below)
Connected	The connection is approved and the last check succeeded	Nothing
Unreachable	The connection is approved, but the last check could not connect. Calls are refused as upstream_unavailable	Check the address, the port and the server log. Details shows the last error
Certificate changed	The server presents another certificate than the approved one. Calls are refused until you approve the new one	Compare the new fingerprint and approve it (below)
Manifest invalid	The server is connected, but the last manifest failed the checks. The gateway keeps the previous manifest	Fix the manifest on the server, then select Refresh in Details

Next to the state you may see the tags Pinned certificate, Plain HTTP and Certificate changed. The State column shows Enabled or Disabled.

Button	Effect
Details	Address, status, last check, last error and the approved connection. Refresh probes the server again and pulls its manifest. It approves nothing and needs no MFA
Edit	Changes the accepted credential types, the type in use, whether the server needs a credential of the user, and Enabled. The address cannot be changed: remove the server and add it again
Disable	Takes the tools out of service. It needs no fresh MFA, while other changes of a server do
Remove	Removes the server. Its tools disappear from the catalog and from tools/list, calls are refused, and the scope mapping entries of its resource types are removed. The system and the users’ connections stay. Needs a fresh MFA

Approve the connection

A pending connection appears at the top of Administration, Approvals, in a card titled Connection of and the server name. The line Connections waiting for approval shows how many wait.

1. Read System claimed by the server. The server names its own system in its manifest, and the gateway sends the users’ credentials for that system to this server. Approve only if this is the system you meant to add.
2. Compare the SHA-256 fingerprint with the one the server writes to its log (the line with event=tls_certificate and fingerprint=sha256:...). Select Copy to copy it. Also read Subject, Issuer, Names (SAN) and Valid until.
3. Read Validates as a trusted CA certificate. If it says No: it can only be pinned, the certificate does not chain to a CA the gateway trusts for this host, and the only mode is a pinned certificate.
4. When the card offers a choice under How the gateway should trust this server, pick one:
   • Trusted CA (chain and host name): a renewed certificate needs no approval.
   • Pinned certificate: only this exact certificate is accepted. A new one has to be approved here again.
5. Select Approve connection. It needs a fresh MFA.

The gateway pins a certificate by the SHA-256 hash of its DER encoding. To trust your company CA for the Trusted CA mode, list its certificate in MCP_SERVER_TRUSTED_CAS on the gateway (see Configuration). The certificate must also name the host of the server address.

When a pinned server later presents another certificate, the state becomes Certificate changed and calls are refused. A card appears with the new fingerprint and the line Approved so far with the old one. Verify with the owner of the server that the certificate was replaced on purpose, then approve.

Approving the connection approves neither the policies nor the tools. They wait below on the same screen.

Approve the policies

Each server brings Cedar policies and declarations of its resource types (the types you use in the scope mapping). After the first pull, and after every later change of either, the server shows Policies and resource types waiting for approval. Its tools stay blocked until you approve them.

1. In Approvals, find the server and select Show differences in the row Policies and resource types waiting for approval.
2. Read Resource types and Policies and schema. The left side is Approved, the right side is Pending, and changed lines are marked. For a first registration the left side is empty.
3. If the source says Source: server, read every policy and declaration with extra care: a running server gave this version, and nobody reviewed it in code.
4. Select Approve policies. It needs a fresh MFA. If you do not approve, nothing that works today breaks: the tools of the server stay blocked.

If the approval invalidates entries of the scope mapping, the portal lists them, and evaluation ignores them until you correct the mapping.

Approve the tools

A tool is listed and callable only when the connection, the policies and the tool definition are all approved. The gateway pulls the manifest at least every 60 seconds and approves nothing it pulls, read tools included. A changed definition makes the tool pending again and hides it from agents (definition_changed).

The list shows for each server its version, Changes (for example new: 1, changed: 1) and State (Pending approval, Active, Disabled or Switched off). Open a server to see its tools. Each tool row shows a status and the risk:

Row label	Meaning
Approved · Read	Approved
New · Write	A tool that was never approved
Changed · Write	The definition differs from the approved one
Risk lowering · Write	The new definition has a lower risk than before (see below)
Switched off · Write	An emergency switch is on

The risk levels are Read, Write and Delete. A tool with the risk Delete needs a code from the user’s Authenticator on every call. The group a user needs follows the risk: mcp-<system>-read, -write or -destructive (see Access).

To approve one tool:

1. Select Show differences in the tool row.
2. Read the definition: description, schema, risk, action and resource. Lines marked - are removed, lines marked + are added. The text Source: manifest pulled by the gateway means the gateway pulled it and nothing is approved yet.
3. Select Approve definition.

If the dialog Approve a definition reported by the server? appears, the definition came from a running server and not from a reviewed pipeline. Approve it only if the description and the schema match what you expect. In the example below the new description tells the model to ignore previous instructions, which is a reason to refuse.

The portal writes hidden characters of a definition as [U+XXXX] markers. If the hash changed but no shown field did, the dialog Approve a change you cannot see? asks for explicit confirmation. If the hash the server gave does not match the shown definition, do not approve it and report it to the administrators of the platform.

Approve many tools at once

Use the buttons above the tool list of a server:

• Select all read-only ticks every pending tool with the risk Read.
• Select all ticks every pending tool.
• Approve selected (n) approves the ticked tools one after another, after the question Approve the selected tools? The dialog lists the changed definitions and the ones reported by the running server, because their differences are not shown in the list.

Tools that lower the risk (Lowers the risk: review and approve it on its own.) and tools that need a classification (Needs a classification: approve it on its own.) have no tick box. If a definition changes after you ticked it, nothing is approved and you review it again. If the gateway asks for a fresh identity confirmation midway, the run stops and says how many tools it approved. Approve the rest one by one.

Risk lowering

If a new definition has a lower risk than the approved one (for example Delete to Write), the tool is hidden from agents until you decide. Approving it lowers the effective level, and for a tool that was irreversible, the requirement for a code from the Authenticator goes away.

1. Select Show differences and read the red message Risk lowering. Check the risk, action and hints lines.
2. Select Approve risk lowering. It needs a fresh MFA.
3. Confirm in the dialog Approve risk lowering? Approve only if the change is intended.

If you do not approve, nothing breaks: the tool stays hidden.

Classify tools of a foreign server

A tool served through an adapter (a foreign server that does not state how dangerous an operation is) arrives with no risk and no action, and agents do not see it until you classify it. The row says To classify, and the button is Classify and approve.

1. Select Show differences and read the definition. The hints of the server are untrusted text and do not affect the choice.
2. Select Classify and approve.
3. In the dialog Tool classification, choose the Risk and the Action, then select Approve with this classification.

The adapter is read only, so the dialog offers only Read and read. A tool that writes or deletes data will not pass through the adapter, so do not approve it. A change of the definition sends the tool back to pending.