MCP servers
How to register Model Context Protocol servers in Console, test their tools, and expose them to agents. The endpoint contract is in the MCP API reference.
An MCP server in Console is a gateway: Console holds the definition and the credentials, discovers the tools, and serves them over the Model Context Protocol. Your agents bind it, and so can any external MCP client (an IDE, another agent platform) with an API token.
Open Build → MCP Servers (/dashboard/mcp). The sub-nav has Servers, MCP Hubs (Enterprise, see MCP Hub) and Monitor.
Where the tools come from
New MCP server asks for a Source type. The form fields of the three classic sources are listed in Build and publish an agent; in short:
| Source type | What Console does | API sourceType |
|---|---|---|
| OpenAPI spec | Parses an OpenAPI or Postman document (paste, upload or fetch from a URL) and turns each operation into a tool that calls your upstream API | openapi |
| Remote MCP URL | Connects to an MCP server you already run (Streamable HTTP or SSE), discovers its tools and proxies calls | remote |
| npx / uvx package | Launches an MCP package (npx or uvx) with its arguments and environment variables. Stateless subprocess is the community execution mode; Persistent sandbox needs an Enterprise licence | stdio |
| Internal service | Publishes a Console capability as MCP tools without writing a spec. The providers registered in this build are Knowledge Base (a Knowledge Engine module: search, read_document, read_document_lines) and Agent Observability | internal |
| Composite (other servers) | Republishes the tools of other MCP servers of the same workspace under one endpoint | composite |
The five values are accepted by the dashboard API (POST /api/mcp). The client API (POST /api/client/v1/mcp) creates openapi, remote and stdio servers only.
Upstream authentication
OpenAPI and remote servers authenticate to their upstream with None, Bearer token, Custom header (name and value) or Basic auth (username and password). Secrets are encrypted at rest and masked in every response. Environment variables of an npx/uvx package are sealed the same way.
Composite servers
A composite is useful when an agent or an IDE should see one endpoint instead of five. For each member you choose a server, an optional tool prefix (default: the member's key) and Always prefix. Member tools keep their own authentication, their own enable/disable and rename overrides, their own request logs and their own guardrail binding; the composite only decides which tools are included and under which name. A tool is prefixed when its name would collide with another member's, or always when Always prefix is on.
Do not make a composite public by accident
Console marks a member that is backed by an internal service (a Knowledge Base, Agent Observability) so that you are warned before the composite is exposed publicly. A public endpoint needs no token.
Expose the server
The Endpoint exposure section of the form decides how callers reach the server:
| Setting | Options |
|---|---|
| Protocols | Streamable HTTP (JSON-RPC) and SSE (legacy); at least one stays on |
| Access mode | API token required (default) or Public URL (no auth) |
| Custom path | Public servers only. Leave blank for a random unguessable path, or set your own stable one: unique within the workspace, at least 8 characters (letters, numbers, hyphens) |
Token-authenticated callers use /api/client/v1/mcp/{serverKey}/...: GET /execute lists the tools, POST /execute runs one, GET /sse and POST /message speak the MCP protocol (version 2024-11-05). A public server is served at /api/public/mcp/{tenantId}/{endpointSlug}/sse and /message. The wire format is documented in the MCP API reference.
Public means anyone with the URL
A Public URL server runs without a token. Anyone who learns the path can call its tools with your upstream credentials. Use it only for tools that are safe to publish, and prefer a random path over a memorable one.
Change a server's key
Each server has a key, shown as Server Key on its Overview tab (the pencil icon changes it). The key is the identifier in the API path (/api/client/v1/mcp/{serverKey}) and the one agents bind by. Set your own key when you create the server through the API (key), or rename it later. Renaming asks for confirmation first because every agent bound to the old key stops resolving it. Keys are slugified and made unique within the project.
Switch off tools you do not need
Open the server's Tools tab. Every tool has a toggle; the header shows N / M enabled. Search by name, path or description, filter by All / Enabled / Disabled, and use Enable / Disable for everything matching the filter. Changes are staged and applied with Save changes.
A disabled tool disappears from tools/list, the client API and every agent that has it bound. The list is stored per server (disabledTools), survives Update tools (rediscovery) and can be set through the API:
curl -X PATCH "$BASE/api/client/v1/mcp/support-tools" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "disabledTools": ["delete_ticket", "export_all"] }'disabledTools is a full replacement list; an empty list enables everything.
Rename and reword tools
The row action Edit description & annotations opens the tool's settings:
| Field | Effect |
|---|---|
| Description | Replaces the description discovered from the spec or the upstream server, everywhere the tool is shown, including to the model |
| Tool name | The name MCP clients and agents call the tool by. Letters, numbers, _ and -, at most 128 characters, unique on the server. Calls under the new name still run the same underlying tool. Clear it to restore the discovered name |
| Title | A human-readable label for MCP clients; cosmetic |
| Annotations | readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Every tool is served with a full set because strict clients reject servers that omit them. Values come from the override, else are derived (read-only for GET/HEAD operations and for internal Knowledge Base tools, otherwise the conservative "not read-only, potentially destructive") |
These overrides are stored per server and survive rediscovery. Descriptions and annotations can also be patched through the client API (toolDescriptions, toolAnnotations, with null removing an override); the tool name override is set from the dashboard (toolNames on PATCH /api/mcp/{id}).
Rename to fix collisions and to guide the model
Two upstreams that both expose search confuse the model. Rename them search_docs and search_tickets, or give each a description that says when to use it.
Pass caller headers to the upstream
Off by default. A server can be told to forward headers that the caller supplies at run time (for example the end user's own Authorization) to its upstream, either all of them or an allow-list of names (runtimeHeaders: { allow, allowedNames }). Leave it off unless the upstream needs the caller's identity.
Guard and monitor
The form's guardrail section (Off, Monitor, Enforce, with the default tool guardrail or one you choose) binds a guardrail that is evaluated at tool.pre and tool.post; see Guardrails. The server's Usage, Request Logs and Audit tabs, and the Monitor page, show every call.
Bind it to an agent
In Add Tools, MCP servers appear under MCP (legacy); tick the tools the agent may call. See Tools overview.
Who can do this
MCP servers belong to the mcp service (MCP Hub in the access settings). Reading needs mcp.read; creating, changing and deleting needs mcp.write. Executing a tool through the client API is checked as mcp-server.call. See the Permissions reference.