MCP Server

The built-in MCP (Model Context Protocol) server gives agents controlled access to Polygent tickets, sessions, memory, plans, and user interaction; external MCP servers extend agents with your own tools.

Built-in tools

Built-in tools let an approved agent retrieve operational context and perform selected interactive or write operations.

Tool	Purpose	Risk class
search_tickets	Search tickets by text, stage, and workspace.	Read
get_ticket_details	Retrieve ticket details, stage history, and session summaries in batches.	Read
get_session_details	Retrieve session messages and summaries in batches.	Read
create_ticket	Show a pre-filled ticket form for the user to confirm (default), or create a Pending ticket, or create and queue it.	Write
ask_user_question	Present one or more multiple-choice questions to the user.	Interactive
send_message	Send an inbox notification to a user or to every member of a workspace.	Write
get_memory_items	Read workspace memory items.	Read
set_memory_items	Add workspace memory items.	Write
remove_memory_items	Remove workspace memory items.	Destructive
write_plan	Create a plan shown in the Chat session's Plan panel.	Write
edit_plan	Change the session's plan.	Write
read_plan	Read the session's plan in a later turn.	Read

When a user answers ask_user_question, the answer is kept if the assigned host is at capacity and the same agent conversation resumes automatically when capacity is available; reloading the page or restarting the service does not discard it.

Built-in tools are granted through the Polygent MCP Tools selection of each bot, template, automation, subagent, and AI job. An empty selection grants none. Use explicit subsets for production bots and automations — for example search_tickets without create_ticket or send_message.

Configure the endpoint URL

The advertised MCP URL tells every session host how to reach the endpoint.

Set McpUrl to an absolute HTTPS URL reachable from the API host and every Session Worker. When McpUrl is not set, Polygent uses {ClientUrl}/mcp. A Session Worker that receives a loopback URL (localhost) replaces it with its own ApiUrl.

{
  "ClientUrl": "https://polygent.example.com",
  "McpUrl": "https://polygent.example.com/mcp"
}

If McpUrl is set but is not a valid absolute URL, Polygent MCP tools are silently omitted from sessions — there is no fallback. Restart the API after changing it.

Security boundary

The /mcp endpoint is authenticated: every request must carry a temporary credential that Polygent issues for one agent run.

• Each credential is bound to the launching user (or automation identity), session, workspace, and the run's granted tools. Calls cannot widen those limits, and workspace membership is rechecked on access.
• Credentials are held in memory, expire after at most 8 hours, are revoked when the run or session ends, and are invalidated by an API restart. Operators never create, distribute, or rotate a built-in MCP key.
• A request without a credential receives 401; an invalid, expired, or revoked credential receives 403.
• The credential is sent as Authorization: Bearer …. Reverse proxies must forward the Authorization header; if a proxy strips it, Polygent also accepts the X-Polygent-Authorization header.

Although the endpoint is authenticated, treat it as an internal agent surface: allow it only from the API and Session Worker networks, block it at the edge for internet-exposed installations, and require TLS.

External MCP servers

External MCP servers extend agent capabilities with your own HTTP-based tools.

Manage them under Developer Tools → MCPs (view with View MCP Servers, change with Manage MCP Servers).

Field	Behavior
Name	Identifier used in tool names; cannot be polygent.
Transport	HTTP (Streamable HTTP) or SSE (legacy). Local (stdio) servers are not supported.
URL	Absolute http or https URL; use https for anything outside the host.
Auth Mode	None, Bearer token, or OAuth 2.1 (see below).
API Key	Bearer token; encrypted at rest and sent as Authorization: Bearer <token>.
Enabled	Disabled servers are never connected.

A server is used only when it is enabled and selected in the session source's MCP Servers list (and, optionally, narrowed with MCP Tools) and permitted by the workspace capability ceiling. Selecting a server connects it; tool access still follows the tool selection.

OAuth 2.1 servers

An OAuth 2.1 server uses one shared connection for the whole installation.

1. Set ClientUrl to the public origin of Polygent with no path (for example https://polygent.example.com).
2. If the provider requires a pre-registered redirect URI, register {ClientUrl}/api/mcp-servers/oauth/callback.
3. An administrator with Manage MCP Servers selects Connect and completes consent in the browser popup.

After connection, every agent that is granted the server acts as the connecting account at the provider; the connecting user is recorded for audit. Tokens are encrypted and refreshed automatically. Temporary network or provider failures keep the connection and retry; reconnection is required only when the provider rejects the authorization. Disconnect removes the stored tokens and Revoke also asks the provider to revoke them.

Servers on private networks

Outbound MCP traffic — tool discovery, tool calls, and OAuth discovery and token requests — is blocked to private, loopback, and link-local addresses. To use an internal MCP server, list its hostname in Mcp:OAuth:AllowedPrivateHosts in the API and every Session Worker appsettings.json, then restart them:

{
  "Mcp": {
    "OAuth": {
      "AllowedPrivateHosts": ["mcp.internal.example.com"]
    }
  }
}

Network verification

Network verification confirms the endpoint is routed without needing a credential.

From each Session Worker:

curl -i https://polygent.example.com/mcp

An HTTP 401 response confirms routing reached the protected endpoint. A connection, DNS, or TLS error indicates a network or proxy problem. From an untrusted network, the request should be blocked before it reaches Polygent.

Troubleshooting

MCP failures normally come from URL resolution, network policy, credential forwarding, or tool scoping.

Symptom	Resolution
No Polygent tools in any session	McpUrl is invalid; correct it or remove it to use {ClientUrl}/mcp, then restart the API.
Endpoint is unreachable from a worker	Verify DNS, TLS trust, proxy routing, and firewall rules for McpUrl from the worker.
HTTP 401 during an agent run	The proxy removed the Authorization header; forward it (or X-Polygent-Authorization).
HTTP 403 during an agent run	The run ended, the API restarted, the user left the workspace, or the tool is not granted.
External server is configured but tools are absent	Check it is enabled and selected, its tool selection, and the capability ceiling.
External server on an internal address fails	Add its hostname to Mcp:OAuth:AllowedPrivateHosts on the API and workers.
OAuth connect fails or loops	Set ClientUrl to the bare public origin and register the callback URI with the provider.
OAuth renewal temporarily failed	Wait; Polygent keeps the refresh credential and retries automatically.
OAuth server requires reconnection	Connect again; the provider rejected the stored authorization.
A built-in tool is absent	Check Polygent MCP Tools on the session source or subagent; an empty list grants none.
Unexpected MCP activity in logs	End the affected session, review its workspace membership and tool grants, and investigate the host environment.