Skip to main content

IDE Integration Troubleshooting

First identify which path is failing:

  • MCP tools use https://<published-hostname>/mcp.
  • Model clients can use the supported Chat Completions, Responses, or Messages route. Each route uses the access, input, tool, output, and audit stages.
  • A client can have one path configured and the other path continue to go directly to its vendor.

MCP server is unavailable​

Do these checks:

  1. The URL is the active agent publication, not the control-plane API and not localhost:41002.
  2. The client sends an active Verdictan API token as a bearer token.
  3. The client supports remote streamable HTTP MCP servers.
  4. The publication is active and its resolved agent configuration has MCP enabled.
  5. The client process can see all environment variables referenced in its MCP configuration.

Use the client's MCP status and output log to examine the HTTP status and JSON-RPC error. A plain browser request is not a useful test because /mcp uses MCP transport headers and protocol messages.

MCP connects but model events are missing​

This occurs if you configure only MCP. MCP adds Verdictan tools. It does not change the model endpoint that the IDE uses. If model requests must also traverse the gateway, configure a supported custom model endpoint.

Local model endpoint refuses the connection​

Start the gateway with the necessary agent binding:

export VERDICTAN_API_TOKEN="<gateway-runtime-token>"
verdictan gateway run \
  --agent ide-gateway \
  --listen 127.0.0.1:41002 \
  --policy-config policy-config.yaml

Verify process health:

curl --fail http://127.0.0.1:41002/healthz

Then examine the authenticated model catalog with a client token:

curl --fail http://127.0.0.1:41002/v1/models \
  -H "Authorization: Bearer ${VERDICTAN_IDE_TOKEN}"

Model endpoint returns 401 or 403​

  • Do not reuse the gateway runtime token in the IDE.
  • Make sure that the client token starts with the Verdictan token prefix and is active in the API Tokens page.
  • Examine expiry, request limits, budgets, roles, bindings, provider filters, and model filters.
  • Make sure that the IDE is sending the token to the gateway endpoint, not to the upstream provider.

verdictan events tail has no requests​

verdictan events tail --since 10m --follow

A matching event proves that the request traversed Verdictan. A missing event does not by itself prove bypass. Verify this sequence:

  1. The gateway mode has event delivery enabled and its runtime token is correct.
  2. The CLI profile points to the same organization, API endpoint, and region as the gateway.
  3. The since window and all active event filters include the reproduced request.
  4. The active IDE model uses the specified Verdictan base URL and client token.

If those checks are correct, examine gateway delivery errors and the selected IDE adapter. Generic HTTP_PROXY and HTTPS_PROXY settings do not turn the model API into a forward proxy.

Policy block or redaction is unexpected​

Tail events while you reproduce the request. Identify the policy and verdict. Change only the policy that generated the verdict. Before you start the gateway again, validate each change:

verdictan policy lint --file policy-config.yaml
verdictan policy test --json

Do not disable all controls in the chain to work around one false positive.

Slow responses​

Measure each segment before you assign latency to the gateway:

  1. Compare healthz and v1/models response time with a representative model request.
  2. Examine gateway events and provider errors.
  3. Verify the model and API type that the client selected.
  4. Keep inline-completion policy chains small.
  5. After you identify the slow segment, adjust the client timeout.

Incorrect locality or empty region-scoped results​

verdictan regions current reports the CLI-requested region. It does not rewrite a provider target or publication locality. Make sure that the active published hostname, gateway configuration, and CLI profile refer to the specified region.

Next steps​