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.

Before you start

• 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 Gateway MCP Surface. 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 connection command from the agent's Setup screen, 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 a client API token

Use the quickstart's application 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 setting	Value
OpenAI-compatible base URL	VERDICTAN_BASE_URL, including /v1
API key	The Verdictan application token
Model	VERDICTAN_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 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

Symptom	Cause	Fix
verdictan gateway run exits at start	The command has --policy-config, which calls control-plane routes that the API does not serve. Or --agent is set and VERDICTAN_API_TOKEN is missing.	Export the gateway runtime token. Run the connection command from the Setup screen without --policy-config. To change the configuration, follow Try the change on a test gateway.
verdictan policy lint prints findings	A provider target or control does not match the schema	Fix each finding and lint again.
/v1/models returns 401	The client token is missing, invalid, or expired	Check the raw Bearer value and the token status in the Console.
/v1/models returns 404 with models_disabled	The policy config turns off the models endpoint	Turn on the models endpoint. Then deploy the configuration to the agent in Configurations again.
/mcp returns 404 with mcp_publication_required	The request went to a local or unpublished hostname	Use the agent's published hostname.
The event tail stays empty	The client base URL, CLI region, or time window does not match	See IDE Integration Troubleshooting.

Next steps

• API Tokens for IDEs: scope, store, and rotate the client token.
• IDE Integration Overview: the setup guide for your editor.
• Configure Policies for IDE Traffic: controls for coding assistants.