Skip to main content

Gateway setup for IDEs

Get a working gateway before you touch editor settings. By the end of this page you have the three values every editor asks for (a base URL, an API key, and a model ID), and you have proven they work with curl.

Needs:
  • The quickstart done, with a Hello reply and the gateway terminal still open. The provider key stays in that gateway's environment.
  • For MCP tools only: an enabled, published MCP endpoint from Connect an MCP client. A model connection does not turn on MCP.

Create and validate the policy config​

For a first editor test, keep the configuration from the quickstart; you don't need a second agent. To set up a separate development agent, follow the config-first workflow and come back here.

Start the connected gateway​

If you changed the YAML, deploy it through the Console or CLI 0.1.14 or later. After the gateway starts, check In sync before you test the editor connection.

Run the gateway command from II Gateway in the Overview setup guide, in the terminal where your provider key is exported, and leave it running while you use the editor.

For a gateway on this computer, check that the process is up:

curl --fail --silent --show-error http://127.0.0.1:41002/healthz

This only shows the process is alive. The next section proves a model request works.

Create an API token​

Use the quickstart's API token for the first test. For day-to-day editor use, create a separate token on the Console API tokens page; see API tokens for IDEs for scope and storage.

  1. In a second terminal, set the base URL and token:

    export VERDICTAN_BASE_URL='http://127.0.0.1:41002/v1'
    export VERDICTAN_CLIENT_TOKEN='your-application-token'

    127.0.0.1 always means the machine that sends the request. If the editor runs elsewhere, or calls from its vendor's cloud, use your agent's published model base URL instead.

  2. List the models the gateway offers:

    curl --fail --silent --show-error "$VERDICTAN_BASE_URL/models" \
      -H "Authorization: Bearer $VERDICTAN_CLIENT_TOKEN"
  3. Copy one returned id and send a request with it:

    export VERDICTAN_MODEL='your-returned-model-id'
    
    curl --fail-with-body --silent --show-error \
      "$VERDICTAN_BASE_URL/chat/completions" \
      -H "Authorization: Bearer $VERDICTAN_CLIENT_TOKEN" \
      -H 'Content-Type: application/json' \
      -d "{\"model\":\"$VERDICTAN_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply with Hello.\"}],\"stream\":false}"

    The response has text in choices[0].message.content. This call uses provider credit. Fix any error here before you configure the editor.

These are the values for your editor:

Editor settingValue
OpenAI-compatible base URLVERDICTAN_BASE_URL, including /v1
API keyThe Verdictan API token
ModelVERDICTAN_MODEL

The editor's API key field takes the Verdictan token. The provider key never leaves the gateway.

Connect an MCP client (optional)​

MCP gives an editor's agent Verdictan tools. Use the URL from the agent's publication:

https://<published-hostname>/mcp

The local model listener and the control-plane API hostname don't serve MCP. Set the Bearer header as described in your editor's guide from the IDE integration overview, and add the Verdictan entry next to your existing MCP servers.

Verify​

For a model connection:

  1. Configure the editor with the three values above.
  2. Send Reply with Hello. from the editor with the configured model, and check that the editor shows an answer.
  3. In a CLI session signed in to the same organization and region, run verdictan events tail --since 10m.
  4. Check that a matching event appears. Delivery can take a few seconds, so run the command again if it is not there yet.

For MCP, check that the server lists its tools and that one read-only tool returns a result. An empty history search is a valid result. A listed server does not prove tool authorization, and a working MCP tool does not prove model routing.

Troubleshooting​

SymptomCauseFix
verdictan gateway run exits at startA required connection, credential, agent binding, or cache setting is missing, or a configuration deployment failedRead the startup error. Export the gateway runtime token and use the agent's connection command. --policy-config also needs --agent and deploys through that agent before startup. See gateway run.
verdictan policy lint prints findingsA provider target or control does not match the schemaFix each finding and lint again.
/v1/models returns 401The API token is missing, invalid, or expiredCheck the raw Bearer value and the token status in the Console.
/v1/models returns 404 with models_disabledThe policy config turns off the models endpointTurn on the models endpoint. Then deploy the configuration to the agent in Configurations again.
/mcp returns 404 with mcp_publication_requiredThe request went to a local or unpublished hostnameUse the agent's published hostname.
The event tail stays emptyThe client base URL, CLI region, or time window does not matchSee IDE integration troubleshooting.

Next steps​