Skip to main content

MCP servers

The MCP servers screen lets you register the Model Context Protocol servers agents may call, list their tools, disable, enable or delete them, and send a JSON-RPC 2.0 request through the MCP gateway. Portal path: /capabilities/mcp. Developers register and test servers; tenant administrators and security officers decide their status. The screen is drawn by portal/src/screens/capabilities.tsx.

What the screen shows​

  • MCP servers table, read with GET /v1/mcp/servers (the servers the request may see, in one call). Columns: Name, Transport, URL, Allowed tools, Status, Created. View details shows the row. Empty: No MCP server, hint Register a server to expose its tools to agents., button New MCP server.
  • New MCP server opens a side panel with Name (required, lowercase letters, digits, ., _, -), URL (required, example https://<mcp-host>/mcp), Transport (required: streamable_http or sse), Allowed tools (comma separated; when empty every tool is allowed, *), Owner, Authentication (JSON, default {"type": "none"}; types none, bearer, api_key, query_param, connector, with a credential_ref of the form openbao://... or env://...).
  • MCP gateway tester: Server id (required), Method (required: "initialize", "tools/list", "tools/call", "resources/list", "resources/read", "prompts/list"), Params (JSON), the button Run and a Result area.
note

MCP servers are internal only. The Control Plane accepts a server hosted by the Navin Manager, an MCP Runtime instance or a host named in EAI_MCP_INTERNAL_HOSTS, checks it at registration and at every call, and refuses a public address with mcp_online_forbidden.

Actions​

Button or actionWhat it doesAPI callRoles
Refresh (icon)Reloads the list.GET /v1/mcp/serversAny tenant member
New MCP serverRegisters the server in the current project.POST /v1/mcp/serverstenant_admin, developer, application_owner
Row menu View detailsShows the row in a side panel.NoneAny tenant member
Row menu ToolsSends "tools/list" to the server and shows the tools that pass the allow list.GET /v1/mcp/servers/{server_id}/toolsRelation can_invoke on the server
Row menu Disable (server not disabled)Form with a required Reason; disables the server at once and audits it.POST /v1/mcp/servers/{server_id}/statustenant_admin, security_officer and relation editor
Row menu Enable (disabled server)Asks for active: opens a promotion approval; the server becomes active once approved.POST /v1/mcp/servers/{server_id}/statustenant_admin, security_officer and relation editor
Row menu DeleteOpens Confirm a destructive action; type the server name, then Confirm.GET /v1/lineage/graph, then DELETE /v1/mcp/servers/{server_id}tenant_admin and relation owner
Run (MCP gateway)Sends the JSON-RPC request through the gateway and shows the reply.POST /v1/mcp/gateway/{server_id}tenant_admin, developer, agent and relation can_invoke
Retry (error state)Sends the failed read again.Same callSame roles

The tester wraps the form in a JSON-RPC 2.0 message; for a "tools/call", Params holds the tool name and its arguments:

{"jsonrpc": "2.0", "id": 1767225600000, "method": "tools/call", "params": {"name": "search", "arguments": {"query": "supplier contract"}}}

The gateway refuses a "tools/call" on a tool outside Allowed tools, asks the scope tools:invoke, and runs the DLP on the arguments.

Roles​

The portal hides no button. In services/control-plane/src/eai/domains/mcp/routes.py: create needs WRITE_ROLES (tenant_admin, developer, application_owner); the status change needs tenant_admin or security_officer; delete needs tenant_admin; the gateway needs OPS_ROLES (tenant_admin, developer, agent). The routes also check the relation on the server (editor, owner, can_invoke), and a request made in a project only sees the servers of that project. platform_admin passes every role check.

Typical tasks​

Register an internal MCP server​

  1. Create it. Agents reach the server only through the gateway. Click New MCP server, fill Name, URL and Transport, list the Allowed tools, set Authentication, then click Create. Expected result: the toast Created and a new row. If it fails: mcp_online_forbidden (403) means the URL resolves to a public address; host the server internally.
  2. List its tools. The list proves the gateway reaches the server. In the row menu, click Tools. Expected result: a side panel with the tools that pass the allow list. If it fails: upstream_error (502) carries the error of the server; check the URL and the authentication.

Call a tool through the gateway​

  1. Fill the tester. The tester sends a real call, audited like the call of an agent. In MCP gateway, type the Server id, choose "tools/call" in Method and write Params with name and arguments. Expected result: the form is complete. If it fails: Invalid JSON under Params means the JSON is malformed.
  2. Run it. Click Run. Expected result: the JSON-RPC reply in Result. If it fails: an error member in the reply says the tool is not in the allow list, or that the scope tools:invoke is missing.

Disable a server during an incident​

  1. Disable it. Disabling applies at once, without approval. In the row menu, click Disable, type the Reason, then click Disable. Expected result: the toast Done and the status Disabled. If it fails: forbidden means you are neither tenant_admin nor security_officer.
  2. Enable it later. Going back to active is a promotion. Click Enable. Expected result: the toast Done and a promotion request in the Approvals inbox; the server becomes active once another person approves it. If it fails: read the error of the approval in the inbox.

Troubleshooting​

SymptomCauseFix
mcp_online_forbidden (403)The URL resolves to a public address.Host the server on the Navin Manager, the MCP Runtime or an internal host of EAI_MCP_INTERNAL_HOSTS.
mcp_server_not_found (404)The id is wrong or the server was deleted.Copy the id from the table (View details).
mcp_project_forbidden (403) or mcp_server_project_mismatchThe request is made in another project than the server.Switch to the project of the server.
mcp_principal_not_allowed (403)You are not among the users and agents allowed on the server.Ask the owner of the server to grant you access.
upstream_error (502) on ToolsThe MCP server answered an error.Check the URL, the transport and the authentication.
Reply with method ... is not allowed through the gatewayThe method is not one of those the gateway relays.Use one of the methods of the Method list.
validation_error (422) on CreateThe name has capitals or spaces, or credential_ref does not start with openbao:// or env://.Fix the field named in the error.