Skip to main content
The fastest way to connect an agent to xysq is the in-app Connect Agent course. It walks you through every step for your specific agent: generating a key (or signing in over OAuth), copying the right config, pasting it into the correct file, and verifying the connection live.

Open the Connect Agent course

Sign in and pick your agent. The course generates your credentials inline, gives you a one-click install where the agent supports it, and confirms the connection before you leave.

​
What the course covers

Step-by-step, agent-specific setup for:
  • Claude Code - plugin install plus OAuth (no key to paste on the default path)
  • Claude (web and desktop) - custom connector over OAuth
  • Cursor - one-click install or manual mcp.json
  • Windsurf - mcp_config.json with a bearer token
  • Antigravity - mcp_config.json with a bearer token
  • ChatGPT - custom connector
  • Generic - any MCP client, by hand
Each path ends with a live verification step, so you know the connection works before you start using it.

​
After connecting: install the skill

The connection gives your agent the xysq tools. The standard skill teaches it when and how to use them. Download it from the Dashboard and drop it in. The install guides cover where the skill file goes for every agent.

​
Two CLI agents the in-app course doesn’t cover yet

Codex CLI and Gemini CLI connect the same way (a remote HTTP MCP server with a bearer token), but they aren’t in the in-app course yet. Set them up by hand using the steps below. First, generate an API key at app.xysq.ai/connect-agent (any agent tab; the key format is identical). It starts with xysq_.

​
Codex CLI

Codex CLI reads MCP servers from ~/.codex/config.toml. Keep the token out of the file by referencing an env var: 
export XYSQ_MCP_TOKEN="xysq_..."

[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 send it as Authorization: Bearer <value>. Or let the interactive command write the block for you: 
codex mcp add xysq
Choose HTTP, paste https://api.xysq.ai/mcp, and select Bearer token from env var. Verify with codex mcp list.

​
Gemini CLI

Gemini CLI reads MCP config from ~/.gemini/settings.json (user scope) or ./.gemini/settings.json (project scope). Use httpUrl for the remote Streamable-HTTP server (not url, which is the deprecated SSE transport): 
export XYSQ_API_KEY=xysq_...

{
  "mcpServers": {
    "xysq": {
      "httpUrl": "https://api.xysq.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${XYSQ_API_KEY}"
      },
      "timeout": 5000
    }
  }
}
Or use the command: 
gemini mcp add --transport http \
  --header "Authorization: Bearer $XYSQ_API_KEY" \
  xysq https://api.xysq.ai/mcp
Verify with gemini mcp list.

​
Work accounts

If you signed in with a business email, connect to your organisation-scoped server instead of the bare URL. The Connect Agent course renders the right URL (https://api.xysq.ai/mcp/org/<your-org-id>) automatically while you’re in your organisation. See Organisations for how the scoping works.

​
Troubleshooting

ProblemFix
Server never connectsConfirm the URL and key are copied exactly. Check VPN or firewall rules for HTTPS to api.xysq.ai.
Auth fails with 401Confirm your token is exported in the shell that launched the agent (echo $XYSQ_API_KEY / echo $XYSQ_MCP_TOKEN).
url not recognisedSome clients use a different field: Windsurf and Antigravity use serverUrl, Gemini CLI uses httpUrl, Cursor and Codex use url.
Tools listed but calls failSome clients cap total MCP tools (Cascade caps at 100). Disable tools you don’t use on other servers.
Work account blocked on /mcpBusiness accounts must connect to /mcp/org/<org-id>. Copy the URL from the Connect Agent course while inside your organisation.