Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xysq.ai/llms.txt

Use this file to discover all available pages before exploring further.

Use the xysq MCP server with OpenAI Codex CLI so Codex can call xysq tools for memory and identity-aware context. Codex CLI supports remote HTTP MCP servers natively as a stable feature — no wrapper required.

​
Before You Connect

Sign in to your xysq account at app.xysq.ai.

​
Step 1 — Generate Your API Key

  1. After logging in, click the Connect Agent button.
  2. Select the Codex tab (or any tab that exposes API keys — the key format is identical).
  3. Click Generate API Key. Copy the xysq_... key — it won’t be shown again.

​
Step 2 — Export the Token

Codex CLI’s recommended pattern is to keep secrets out of the config file and reference them by environment variable: 
export XYSQ_MCP_TOKEN="xysq_..."
Add this to your ~/.zshrc, ~/.bashrc, or shell profile so it persists.

​
Step 3 — Edit Codex CLI Config

Codex CLI reads MCP servers from ~/.codex/config.toml (TOML, not JSON). Open the file (create it if it doesn’t exist): 
mkdir -p ~/.codex
$EDITOR ~/.codex/config.toml
Add the xysq server block: 
[mcp_servers.xysq]
url = "https://api.xysq.ai/mcp"
bearer_token_env_var = "XYSQ_MCP_TOKEN"
enabled = true
startup_timeout_sec = 10
tool_timeout_sec = 60
bearer_token_env_var tells Codex to read the named env var and inject it as Authorization: Bearer <value> on every request. If you’d rather use a static header (less safe): 
[mcp_servers.xysq]
url = "https://api.xysq.ai/mcp"
http_headers = { "Authorization" = "Bearer YOUR_API_KEY" }

​
Step 3 (alternative) — Use codex mcp add

Codex CLI ships an interactive command that writes the same block for you: 
codex mcp add xysq
Follow the prompts: choose HTTP, paste https://api.xysq.ai/mcp, and select Bearer token from env var when asked.

​
Step 4 — Verify

codex mcp list
You should see xysq listed with its status. From inside a Codex session, type /mcp to see live tools and connection state.

​
Step 5 — Use It

Start a Codex session: 
codex
Then ask for memory-aware behaviour: 
Remember that I prefer Python 3.12 for new projects.
What's my current project context?
Codex will call xysq tools through MCP as needed.

​
Pinning Codex to a team vault

To scope Codex to a specific team, change the URL: 
[mcp_servers.xysq-acme]
url = "https://api.xysq.ai/mcp/team/YOUR_TEAM_ID"
bearer_token_env_var = "XYSQ_MCP_TOKEN"
enabled = true
Find YOUR_TEAM_ID in Team Settings at app.xysq.ai. Team-pinned connections route all memory actions to the team vault and disable personal-only tools. You can register multiple entries (xysq, xysq-acme, xysq-platform) and switch via the agent — no file editing required between contexts.

​
Approval flow

Codex CLI respects its global approval mode (Auto, Limited, Full Access) for MCP tool calls. If you’re being prompted on every memory call, raise the mode via /permissions inside a session.

​
Troubleshooting

ProblemFix
codex mcp list doesn’t show xysqConfirm the TOML block is under [mcp_servers.xysq] exactly (not [mcp_server.xysq] or [mcp-servers.xysq]).
Auth fails with 401Confirm XYSQ_MCP_TOKEN is exported in the shell that launched Codex. Run echo $XYSQ_MCP_TOKEN to check.
Connection times outBump startup_timeout_sec to 30. Some networks need longer for the OAuth handshake.
Tool calls hangBump tool_timeout_sec to 120 if you’re doing large recalls.
Wrong vault scopeConfirm the url is /mcp for personal or /mcp/team/<id> for a team.

​
Next: install the Skill

The MCP connection gives Codex the tools. The xysq Skill teaches it how to use them. Install the skill →