Configure Coding Agents

Coding agents such as OpenCode run on your workstation, where they can read files, edit code, and run commands. You can route their model requests through the ConfidentialMind Model Gateway and give them access to gateway-hosted RAG tools.

This guide configures OpenCode with two gateway surfaces:

• The OpenAI-compatible API at https://api.YOUR_DOMAIN/v1 for model calls.
• The remote MCP endpoint at https://api.YOUR_DOMAIN/mcp/ for RAG and other gateway-hosted tools.

OpenCode remains the agent loop. It executes local tools itself and calls the gateway's MCP endpoint when the model selects a gateway-hosted tool.

Before you begin

You need:

• OpenCode installed on your workstation.
• Your Model Gateway domain — shown as API URL at the bottom of the portal sidebar, next to a button that copies it.
• A personal API key with invoke granted on the model you want to use.
• For RAG tools, an API key with read granted on each RAG the agent may search.
• A chat model that supports tool calling and is suitable for coding tasks.

A single key can carry both model and RAG grants. You can also use separate keys so model and RAG access can be rotated or revoked independently.

1. Export your API keys

Set the keys in the shell from which you will start OpenCode:

export CM_MODEL_API_KEY='cm_api_…'
export CM_RAG_API_KEY='cm_api_…'

If one key has both grants, export the same value for both variables. Keep the keys out of opencode.json and version control.

2. Find the model ID

List the chat models the model key is allowed to invoke:

curl -sS "https://api.YOUR_DOMAIN/v1/models" \
  -H "Authorization: Bearer $CM_MODEL_API_KEY"

Choose the exact id of a coding-capable model from the response. The display name is not interchangeable with the ID.

3. Configure OpenCode

Create opencode.json in the root of your project. To use the provider for every project, put the same configuration in ~/.config/opencode/opencode.json instead.

Replace YOUR_DOMAIN and MODEL_ID. The limits in these examples are the tested values for Qwen3.6 27B; use the served model's limits when configuring a different model. Consult the model's official page or model card for its supported inputs, tool calling, reasoning options, and token limits, and confirm the limits configured on your deployment. See OpenCode's v1 model settings or v2 model settings for how to express those settings in your config.

Choose the example for your installed version. If you are upgrading, follow OpenCode's Migrate from V1 guide.

OpenCode v1

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "cmgw": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "CM Gateway",
      "options": {
        "baseURL": "https://api.YOUR_DOMAIN/v1",
        "apiKey": "{env:CM_MODEL_API_KEY}"
      },
      "models": {
        "MODEL_ID": {
          "name": "Qwen3.6 27B via CM Gateway",
          "limit": {
            "context": 262144,
            "output": 32768
          }
        }
      }
    }
  },
  "mcp": {
    "cm-gateway": {
      "type": "remote",
      "url": "https://api.YOUR_DOMAIN/mcp/",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:CM_RAG_API_KEY}"
      }
    }
  }
}

OpenCode v2

V2 uses providers, package, settings, and mcp.servers. The aisdk: prefix retains the same AI SDK adapter as in the v1 example. MCP servers connect by default, so the v1 enabled field is omitted.

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "cmgw": {
      "package": "aisdk:@ai-sdk/openai-compatible",
      "name": "CM Gateway",
      "settings": {
        "baseURL": "https://api.YOUR_DOMAIN/v1",
        "apiKey": "{env:CM_MODEL_API_KEY}"
      },
      "models": {
        "MODEL_ID": {
          "name": "Qwen3.6 27B via CM Gateway",
          "limit": {
            "context": 262144,
            "output": 32768
          }
        }
      }
    }
  },
  "mcp": {
    "servers": {
      "cm-gateway": {
        "type": "remote",
        "url": "https://api.YOUR_DOMAIN/mcp/",
        "oauth": false,
        "headers": {
          "Authorization": "Bearer {env:CM_RAG_API_KEY}"
        }
      }
    }
  }
}

In both examples, cmgw/MODEL_ID combines the local provider name with the model ID sent to the gateway. @ai-sdk/openai-compatible uses /v1/chat/completions, including streaming and client-driven tool calls.

The cm-gateway MCP server exposes only the tools the RAG key is authorized to use. To expose RAG tools only and hide other gateway-hosted MCP tools, change its URL to https://api.YOUR_DOMAIN/mcp/?kind=rag.

4. Verify the connections

Check that OpenCode loads the model. With v1, filter by provider:

opencode models cmgw

With v2, list models and look for cmgw/MODEL_ID:

opencode models

Check the MCP connection:

opencode mcp list

The output should show cm-gateway as connected.

Run a model-only check:

opencode run --model cmgw/MODEL_ID \
  "Reply with: ConfidentialMind gateway reached"

Then verify a gateway-hosted RAG call:

opencode run --model cmgw/MODEL_ID \
  "Use an available cm-gateway RAG search tool to answer a question about the indexed documents."

In interactive OpenCode, run opencode and use /models to select the model under CM Gateway.

How tool calls are routed

1. OpenCode sends the conversation and available tool declarations to /v1/chat/completions.
2. The model returns a tool call.
3. OpenCode executes local tools on your workstation.
4. For a cm-gateway MCP tool, OpenCode calls /mcp/; the gateway authorizes and executes the RAG call.
5. OpenCode returns the tool result to the model for the next step.

The model API key and RAG API key are checked independently. Giving the model key invoke does not grant RAG access, and giving the RAG key read does not grant model access.

Configure another coding agent

An agent must support both a custom OpenAI-compatible model provider and a remote streamable-HTTP MCP server:

Integration	URL	Authentication	Selection
Model provider	https://api.YOUR_DOMAIN/v1	API key with model invoke	Exact ID from GET /v1/models
Gateway tools	https://api.YOUR_DOMAIN/mcp/	Bearer API key with RAG read	Tools are filtered by grants

The coding agent remains responsible for the agent loop. The gateway routes model calls, federates authorized RAG tools, executes gateway-hosted tool calls, and records usage and audit events.

Troubleshooting

Symptom	Check
Model request returns 401	Key is exported as CM_MODEL_API_KEY, unexpired, and neither revoked nor disabled.
Model request returns 403	The model key has invoke granted on the configured model.
Model not found	MODEL_ID exactly matches an id returned by GET /v1/models, and the model is ready.
cm-gateway is disconnected	The MCP URL ends in /mcp/ and the authorization header includes Bearer.
No RAG tools appear	The RAG is ready and the RAG key has read granted on it.
The model writes tool calls as text	Select a coding or instruction model with tool-calling support.
Context is truncated too early	Set limit.context and limit.output to the selected model's served limits.

A disabled key can be enabled again from the API Keys page. Enabling preserves expiry dates and grants; the secret must still be unexpired and have the required permissions.

For the complete configuration schema, see the OpenCode docs for your version:

• v1: Providers and MCP servers.
• v2: Providers and MCP servers.