MCP Server

The built-in MCP server gives approved agents controlled access to Polygent ticket, session, interaction, and memory operations.

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 with supported filters.	Read
get_ticket_details	Retrieve ticket details in batches.	Read
get_session_details	Retrieve session details in batches.	Read
create_ticket	Prepare or create a ticket according to the calling session's mode.	Write
ask_user_question	Present structured questions to the user.	Interactive
get_memory_items	Read workspace memory items.	Read
set_memory_items	Add workspace memory items.	Write
remove_memory_items	Remove workspace memory items.	Destructive

The Tools & Capabilities editor can expose all, none, or an explicit subset of Polygent MCP tools. Use explicit subsets for production bots and automations.

Configure the endpoint URL

The advertised MCP URL tells sessions and remote workers how to reach the endpoint.

Set McpUrl to an absolute HTTP or HTTPS URL. If it is omitted, Polygent derives the endpoint from ClientUrl when available. For remote workers, use a hostname reachable from the worker network; do not publish localhost unless the worker runs on the same machine.

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

Equivalent environment configuration:

ClientUrl="https://polygent.example.com"
McpUrl="https://polygent.example.com/mcp"

Restart the API after changing application configuration. Confirm that the network policy permits trusted workers while denying untrusted clients.

Additional MCP servers

Additional MCP servers extend agent capabilities beyond the built-in Polygent tools.

Register only trusted servers, use TLS for network transports, and store credentials in the provided secret field rather than prompts. Then select the server in the relevant bot, automation, template, or subagent. An enabled server is not necessarily exposed: effective access also depends on session selection and workspace capability limits.

Each server chooses one authentication mode:

• None — no Authorization header.
• Bearer token — a static token you paste; it is encrypted at rest and sent as Authorization: Bearer <token>.
• OAuth 2.1 — a single shared connection. An administrator with Manage MCPs clicks Connect, completes consent in a browser popup, and the server's tools become available to every Polygent agent, which then act as that account at the provider. The connecting user is recorded for audit. Polygent stores the tokens (encrypted) and refreshes them automatically; you can Disconnect or Revoke at any time. Temporary network, provider, response, or persistence failures preserve the connection and retry later. Reconnection is required only when the provider rejects the authorization or no refresh credential exists. This requires ClientUrl to be configured so the provider can redirect back after consent.

Security boundary

Each agent run receives a temporary credential bound to its launching identity, session, workspace, and effective built-in tool selection. The endpoint is intended for agent traffic. Keep TLS enabled, ensure reverse proxies forward the Authorization header, and restrict endpoint reachability to trusted worker networks as defense in depth. Operators do not need to create, distribute, back up, or rotate a built-in MCP key.

Network verification

Network verification confirms that the route is reachable while leaving credential issuance to Polygent.

From the same network as the worker:

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

An HTTP 401 response confirms that routing reached the protected endpoint. A connection, DNS, or TLS error indicates a network configuration problem.

Troubleshooting

MCP failures normally come from URL resolution, network policy, expired run context, or tool scoping.

Symptom	Resolution
Endpoint is unreachable	Verify DNS, TLS trust, reverse-proxy routing, firewall rules, and that McpUrl is reachable from the worker.
HTTP 401 during an agent run	Ensure the reverse proxy forwards the Authorization header and does not replace it.
HTTP 403 during an agent run	Confirm the session is still active, the user still belongs to the workspace, and the requested tool is allowed.
Works on the API host but not a remote worker	Replace loopback or private-only URLs with a worker-reachable McpUrl, then review network allowlists.
Server is configured but tools are absent	Check that the server is enabled and selected, then check tool allowlists and workspace capability limits.
OAuth renewal temporarily failed	Retry tool discovery or the agent run later. Polygent preserves the refresh credential and retries automatically.
OAuth server requests reconnection	Connect the server again; the provider rejected the authorization or no renewable credential is available.
A built-in tool is absent	Check Allowed Polygent MCP Tools on the calling session source or subagent. An explicit empty list exposes none.
Unexpected MCP access appears in logs	End the affected session, review its workspace membership and tool grants, and investigate the worker environment.