Codex

Connect ChatGPT's Codex CLI and other OpenAI agents to vTilt's MCP server.

OpenAI Codex (and the broader ChatGPT agent ecosystem) speak MCP. The Codex CLI ships a codex mcp add one-liner; ChatGPT Desktop reads the same ~/.codex/mcp.json file. Either route gets vTilt working in a couple of minutes.

#1. Add the server with the CLI

codex mcp add \
  --name vtilt \
  --url 'https://www.vtilt.com/api/mcp' \
  --header 'Authorization: Bearer vtu_YOUR_SECRET'

bash

This writes the entry to ~/.codex/mcp.json for you. Restart any running codex agents to pick it up.

If your Codex version doesn't have the mcp add subcommand, edit ~/.codex/mcp.json directly:

{
  "mcpServers": {
    "vtilt": {
      "url": "https://www.vtilt.com/api/mcp",
      "headers": {
        "Authorization": "Bearer vtu_YOUR_SECRET"
      }
    }
  }
}

json

#2. Pin a project (multi-project users only)

Pass an extra --header:

codex mcp add \
  --name vtilt \
  --url 'https://www.vtilt.com/api/mcp' \
  --header 'Authorization: Bearer vtu_YOUR_SECRET' \
  --header 'x-vtilt-project-id: YOUR_PROJECT_ID'

bash

Or in the JSON form:

{
  "mcpServers": {
    "vtilt": {
      "url": "https://www.vtilt.com/api/mcp",
      "headers": {
        "Authorization": "Bearer vtu_YOUR_SECRET",
        "x-vtilt-project-id": "YOUR_PROJECT_ID"
      }
    }
  }
}

json

Single-project accounts don't need this — the server auto-pins.

#3. Verify the connection

codex mcp ls

bash

You should see vtilt listed with its URL. Then start an agent:

codex

bash

Inside the prompt, ask:

What MCP tools do I have available from the vtilt server?

text

The agent will call tools/list and summarise the seven phase-1 tools. From there you can ask analytics questions and the agent will call the right tools automatically.

#4. Filter the tool list (optional)

If you want to keep the agent focused, register vTilt under multiple names with ?features= or ?tools= filters:

codex mcp add \
  --name vtilt-analytics \
  --url 'https://www.vtilt.com/api/mcp?features=analytics' \
  --header 'Authorization: Bearer vtu_YOUR_SECRET' \
  --header 'x-vtilt-project-id: YOUR_PROJECT_ID'

codex mcp add \
  --name vtilt-people \
  --url 'https://www.vtilt.com/api/mcp?features=persons,events,recordings' \
  --header 'Authorization: Bearer vtu_YOUR_SECRET' \
  --header 'x-vtilt-project-id: YOUR_PROJECT_ID'

bash

Both ?features= and ?tools= apply with union semantics — a tool survives if it matches either.

#5. ChatGPT Desktop

ChatGPT Desktop's MCP support reads from the same ~/.codex/mcp.json file. After running codex mcp add once, fully quit and relaunch ChatGPT Desktop — the new server appears in the 🔌 menu next to the input box.

#Troubleshooting

codex mcp ls doesn't list vtilt — the JSON file is malformed or the agent didn't pick up the change. Open ~/.codex/mcp.json and validate it with node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))' ~/.codex/mcp.json.
"Unauthorized" — bearer header is missing, malformed, revoked, or expired. See the error table.
"Forbidden — project_not_accessible" — x-vtilt-project-id points at a project you can't access. Remove the header or pick a project from your dashboard.
Rate limit hit — you've made more than 60 requests in the last minute on this key. The agent will surface retryAfter; back off and retry.

#Next steps

Authentication — full key lifecycle and error reference.
MCP server overview — the seven phase-1 tools and example prompts.
Cursor / Claude Desktop / VS Code — same key, different client.