# Connect ChatGPT Desktop to Axiom

**Transport:** stdio (local), HTTP/SSE (connectors GA — Phase 5 for Axiom)
**Auth:** local-stdio (Phase 0); token + principal auth Phase 5
**Status:** Untested — recipe inferred from upstream docs

ChatGPT Desktop ships an MCP client. Local stdio servers can be added
via Settings -> Connectors -> Custom; remote HTTP/SSE connectors are
listed in the same UI.

## Install prerequisites

- ChatGPT Desktop with Connectors enabled (Plus or Team subscription as
  of 2026-Q2).
- Same Axiom prerequisites as the other recipes.

## Configure the connection

Open ChatGPT Desktop -> Settings -> Connectors -> Add custom connector ->
choose "Local (stdio)" and fill in:

| Field | Value |
|---|---|
| Name | `axiom-root` |
| Command | `/absolute/path/to/.venv/bin/axi` |
| Arguments | `mcp serve` |
| Working directory | (your project root, optional) |
| Environment | (optional `PYTHONPATH=...` for worktree usage) |

Or, equivalently, write the JSON manifest directly. The desktop app
stores connector configs at:

- macOS: `~/Library/Application Support/ChatGPT/connectors.json`
- Windows: `%APPDATA%\ChatGPT\connectors.json`
- Linux: `~/.config/ChatGPT/connectors.json`

Block:

```json
{
  "connectors": [
    {
      "name": "axiom-root",
      "transport": "stdio",
      "command": "/absolute/path/to/.venv/bin/axi",
      "args": ["mcp", "serve"]
    }
  ]
}
```

## Verify

In ChatGPT Desktop, start a new chat with the connector enabled (toggle
in the composer's tools menu). Ask:

```
List the available MCP tools, then call axiom_node__hooks_list with no
arguments.
```

Expected: tool list starting with `axiom_memory__*`, `axiom_federation__*`,
`axiom_rag__retrieve`, `axiom_signals__brief`, `axiom_node__hooks_list`.
The hooks_list call returns:

```json
{
  "node": "/Users/<you>/.axiom",
  "hooks_total": 0,
  "events_observed": [],
  "by_event": {}
}
```

## Notes

- ChatGPT Desktop's MCP support is still maturing. UI labels and the
  exact connector-config file path may shift between releases; the
  underlying transport contract (stdio + JSON-RPC per the MCP spec) is
  stable.
- Remote HTTP/SSE connectors require Axiom's Phase 5 work
  (`auth = "token"` and `auth = "principal"` modes per ADR-038 D6).
  Until then, stick with the local stdio path above.
- ChatGPT Desktop sandboxes connectors aggressively. If the venv lives
  inside a directory outside the user home, you may need to grant
  filesystem access in macOS System Settings -> Privacy & Security.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| Connector greyed out | sandbox denied path | Move venv under `~/`, or grant Files & Folders access |
| "command not found" | absolute path required | Run `which axi`, paste the full path |
| Tools list empty | extensions not on PYTHONPATH | Add to env in connector config |

## References

- ADR-038 §D6 (auth staging), §D7
- OpenAI MCP docs: https://platform.openai.com/docs/mcp

_Copyright (c) 2026 B-Tree Ventures, LLC. Apache-2.0 licensed._
