Codex

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'

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"
      }
    }
  }
}

#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'

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"
      }
    }
  }
}

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

#3. Verify the connection

codex mcp ls

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

codex

Inside the prompt, ask:

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

The agent will call tools/list and summarise the boot toolsets (meta + context + analytics + query + docs). Feature toolsets (recordings, AI memory, Google Ads) are auto-listed when your pinned project has that feature connected. From there you can ask analytics questions and the agent will call the right tools automatically — enabling the remaining on-demand toolsets (persons, campaigns, …) with enable_toolset when a question needs them. If your client caches the catalogue and a freshly enabled tool isn't found, pin it on the URL with ?toolsets= instead (see Selecting toolsets).

#4. Pin a fixed toolset (optional)

By default the agent boots with the default toolsets and enables more on demand with enable_toolset. To lock the surface, register vTilt under multiple names with ?toolsets= (or ?tools=) filters — see Selecting toolsets for valid ids:

codex mcp add \
  --name vtilt-analytics \
  --url 'https://www.vtilt.com/api/mcp?toolsets=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?toolsets=persons,recordings' \
  --header 'Authorization: Bearer vtu_YOUR_SECRET' \
  --header 'x-vtilt-project-id: YOUR_PROJECT_ID'

A static ?toolsets= value overrides the session-enabled set (the always-on meta + context toolsets are always included); ?tools= force-includes individual tools. Both apply with union semantics.

#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.