Agent setup

Primary setup is one URL. Loadoutz keeps provider auth server-side and your client authenticates once to the Loadoutz connection.

MCP transport is JSON-RPC 2.0 over HTTP POST. Call initialize once, then tools/list before your first tools/call.

Connection flow

Copy URL: https://mcp.loadoutz.io/mcp/u/<owner-id>
  -> client sends first request without token
  -> server returns 401 + OAuth resource metadata challenge
  -> client completes OAuth 2.1 + PKCE
  -> client stores/refreshes tokens automatically
  -> initialize -> tools/list -> tools/call

Jump to your client

Codex App Codex VS Code OpenCode

Golden path

1. In Loadoutz, install/auth providers and add the right tools to a loadout.
2. Create a connection for your workspace + client.
3. Copy the exact setup URL from the Connections panel.
4. Paste it into your client config or use the generated deep link / command path.
5. Complete OAuth when the client prompts.
6. In the client, run initialize, then tools/list.

Quick verify (discovery challenge)

curl -i -sS "https://mcp.loadoutz.io/mcp/u/<owner-id>"

Expected: 401 plus WWW-Authenticate with resource_metadata=. That confirms OAuth discovery is wired.

Debug-only authenticated call (if you already have an OAuth access token):

curl -sS -X POST "https://mcp.loadoutz.io/mcp/u/<owner-id>" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <oauth-access-token>" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Client setup

Codex App

Use the Connections panel URL:

URL: https://mcp.loadoutz.io/mcp/u/<owner-id>
Complete OAuth prompt in-app/browser.
If server does not appear immediately, fully reload/restart Codex App.

Tip: give the agent a short runtime instruction set so it reruns tools/list after loadout changes and uses code mode only for multi-step jobs.

# Loadoutz MCP Runtime Skill

1. Always call the MCP endpoint with POST JSON-RPC. Never use GET for tool methods.
2. Run initialize once, then tools/list before first tools/call.
3. Re-run tools/list after state changes:
   - switch_loadout
   - consent/loadout authorization updates
   - OAuth reconnect
4. Read inputSchema before tools/call and send required arguments.
5. Treat -32602 as schema/arguments mismatch first.
6. If MCP returns invalid_token:
   - reconnect OAuth for /mcp/u/<owner>
   - rerun initialize then tools/list

Codex (CLI)

Global config lives in ~/.codex/config.toml.

[mcp_servers.loadoutz]
url = "https://mcp.loadoutz.io/mcp/u/<owner-id>"
enabled = true

After editing config, reload/restart Codex so the MCP server is re-registered.

VS Code

VS Code setup is usually project-scoped. Create .vscode/mcp.json in the workspace folder.

{
  "servers": {
    "loadoutz": {
      "type": "http",
      "url": "https://mcp.loadoutz.io/mcp/u/<owner-id>",
      "oauth": true
    }
  }
}

Continue.dev uses a YAML config file. If you use Continue, follow these notes.

Workspace required: open the target project folder in VS Code first.

Continue config target:
.continue/mcpServers/new-mcp-server-<n>.yaml

URL:
https://mcp.loadoutz.io/mcp/u/<owner-id>

Auth mode:
OAuth 2.1 + PKCE (client-managed)

Find latest config file:
ls -t .continue/mcpServers/new-mcp-server*.yaml | head -1

OpenCode

OpenCode supports global or project-scoped config:

Global: ~/.config/opencode/opencode.json
Project: .opencode.json (recommended when you want per-repo isolation)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "loadoutz": {
      "type": "remote",
      "url": "https://mcp.loadoutz.io/mcp/u/<owner-id>",
      "enabled": true,
      "oauth": true
    }
  }
}

Recovery

If client reports invalid_token, reconnect OAuth for this owner URL and rerun initialize then tools/list.

Direct calls vs code mode

Use direct tools/call when you already know which tool you want.
Use code mode when the job needs multiple tool calls, intermediate reasoning, or small scripts between calls.
Code mode only appears when the active loadout has eligible tools.
Focused loadouts keep both direct calls and code mode from bloating the agent context surface.

If your client fails with 405 on GET, that's expected. MCP owner endpoints are POST-only.

Need help next?

Quickstart Agent setup Troubleshooting Resources