Skip to main content

IDE Integration Troubleshooting

First identify which path is failing:

  • MCP tools use https://<published-hostname>/mcp.
  • Governed model traffic should use a custom Chat Completions or Responses endpoint. The Messages route has a weaker policy boundary and is not the recommended IDE path.
  • A client can have one path configured and the other path still go directly to its vendor.

MCP server is unavailable​

Check all of the following:

  1. The URL is the active agent publication, not the control-plane API and not localhost:41002.
  2. The client sends an active Keeptrusts 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 any environment variable referenced in its MCP configuration.

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

MCP connects but no model events appear​

This is expected if only MCP is configured. MCP adds Keeptrusts tools; it does not change the model endpoint used by the IDE. Configure a supported custom model endpoint if you also need model requests to traverse the gateway.

Local model endpoint refuses the connection​

Start the gateway with the required agent binding:

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

Check process health:

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

Then check the authenticated model catalog with a client token:

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

Model endpoint returns 401 or 403​

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

Requests do not appear in kt events tail​

kt events tail --since 10m --follow

A matching event proves that the request traversed Keeptrusts. A missing event does not by itself prove bypass. Check, in order:

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

If those checks are correct, inspect 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 reproducing the request, identify the policy and verdict, then narrow the owning policy configuration. Validate every change before restarting:

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

Do not disable the whole chain to work around one false positive.

Slow responses​

Measure each segment instead of assuming gateway overhead:

  1. Compare healthz and v1/models response time with a real model request.
  2. Inspect gateway events and provider errors.
  3. Check whether the client selected a different model or API type.
  4. Keep inline-completion policy chains intentionally small.
  5. Adjust the client timeout only after identifying the slow segment.

Wrong locality or empty region-scoped results​

kt regions current reports the CLI-requested region. It does not rewrite a provider target or publication locality. Confirm the active published hostname, gateway configuration, and CLI profile refer to the intended region.

Next steps​