Connect an MCP Client

MCP lets an AI client use tools from a different application. Connect it to Verdictan to search permitted history, examine gateway information, or validate a policy.

This connection exposes tools. To send model prompts through Verdictan, use the model API connection.

1. Get the URL and token

Before you start, you must have an active gateway, a published agent hostname, and an application token authorized for that agent.

1. Open the agent in Agents in the Console.
2. Copy its central agent URL.
3. Use the same hostname with the path /mcp.

https://<your-published-hostname>/mcp

Use an Access Key or Gateway Key from API Tokens. Do not use the credential that starts the gateway. Set VERDICTAN_MCP_TOKEN in the environment of the client process.

An unpublished agent or an ordinary localhost listener does not supply this hosted endpoint.

2. Configure your client

Replace <your-published-hostname> in one of these examples. Keep the token in the environment. Do not put it in the configuration file.

Codex CLI

codex mcp add verdictan \
  --url "https://<your-published-hostname>/mcp" \
  --bearer-token-env-var VERDICTAN_MCP_TOKEN

Cursor

Add this entry to your project's .cursor/mcp.json. Keep the other server entries in the file:

{
  "mcpServers": {
    "verdictan": {
      "url": "https://<your-published-hostname>/mcp",
      "headers": {
        "Authorization": "Bearer ${env:VERDICTAN_MCP_TOKEN}"
      }
    }
  }
}

Cursor must have the environment variable when it starts. See Cursor's MCP configuration for supported variable interpolation.

The configuration above is sufficient. A Verdictan repository checkout or installation script is not necessary.

3. Verify the connection

Open the client's MCP server list. Make sure that verdictan connects. Tell the client to list the available tools before you request an operation.

Result: the client can retrieve the gateway's tools/list response. The gateway version and authorization control which tools are available. A saved configuration entry does not show a connection.

What you see	Checks
Authentication or access error	The client received the token, the token is active, and it can access this agent.
mcp_publication_required	Use the published agent hostname, not an API host or localhost URL.
Gateway unavailable	Keep the gateway open. Examine its Console heartbeat.
Missing tool	Examine the returned tool list. Each release can expose different tools.

Supported transport

The hosted MCP surface uses streamable HTTP:

Route	Use
POST /mcp	Client-to-server JSON-RPC requests such as initialize, tools/list, tools/call, resources/list, resources/read, and ping
GET /mcp	Server-sent events stream for server-to-client notifications

The route operates only on a published hostname. An /mcp request without publication context fails closed with an mcp_publication_required error.

Supported capabilities

The published gateway exposes a governed MCP bundle. Use tools/list and resources/list to identify the capabilities of the connected gateway version.

Surface	Tools and resources
History and audit	history_search, events_query, request_trace_get, history://sessions, and history://session/{id} give a traceable history of operations.
Catalog and telemetry	Catalog tools, pricing, and telemetry resources let an agent examine the live gateway.
Regions and gateway state	regions_list, region_get, gateway://effective-config, gateway://tool-servers, regions://catalog, and regions://organization expose locality and governed runtime state.
Context fabric	session_init, context_search, context_share, context_recent, and schema_lookup support shared engineering context. Related context resources give team, branch, schema, and recent context.
Governance	policy_lint, policy_test, tool_servers_list, tool_server_get, and tool_server_validate expose Verdictan governance workflows.

Remote policy_lint accepts only inline YAML in the yaml argument, with a maximum size of 1 MiB. It does not accept a file path. To lint a file on disk, run verdictan policy lint --file <path> locally. For remote policy_test, use inline yaml. A pack_dir value refers to the file system of the published gateway process, not to the MCP client.

Boundary with gateway MCP routing

Surface	Use
Published hostname /mcp	Expose Verdictan itself as a gateway-hosted MCP server
providers.targets[].mcp	Route gateway traffic to an external MCP backend
tool_servers	Record inspection metadata without an active tool server

Limits and failure behavior

Remote policy_lint rejects inline YAML larger than 1 MiB. The tool and resource lists show the capabilities of the connected version.

Next steps

• API tokens for IDEs: control the resources that the client can access.
• Gateway setup for IDEs: connect an application to your gateway.
• Execution targets and runners: configure an external MCP backend.