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 Gemini CLI so Gemini can call xysq tools for memory and identity-aware context. Gemini CLI supports remote HTTP MCP servers natively (Streamable HTTP transport). 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 any tab that exposes API keys (Cursor, Codex, etc — the key format is identical).
  3. Click Generate API Key. Copy the xysq_... key — it won’t be shown again.

​
Step 2 — Pick a Scope

Gemini CLI reads MCP server config from two places:
ScopeFile
User (all projects)~/.gemini/settings.json
Project (this repo only)./.gemini/settings.json
Project scope takes precedence when both define the same server name. Most users want user scope.

​
Step 3 — Add the xysq Entry

Open the settings file (create it if it doesn’t exist): 
mkdir -p ~/.gemini
$EDITOR ~/.gemini/settings.json
Add the mcpServers block. If the file already has other settings, merge mcpServers in alongside them: 
{
  "mcpServers": {
    "xysq": {
      "httpUrl": "https://api.xysq.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      },
      "timeout": 5000
    }
  }
}
Replace YOUR_API_KEY with the key from Step 1. For safer secret handling, use env-var expansion. Export the token first: 
export XYSQ_API_KEY=xysq_...
Then reference it in the config: 
{
  "mcpServers": {
    "xysq": {
      "httpUrl": "https://api.xysq.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${XYSQ_API_KEY}"
      },
      "timeout": 5000
    }
  }
}
Gemini CLI uses httpUrl for remote Streamable-HTTP servers (the modern standard) and url for the deprecated SSE transport. Always use httpUrl for xysq.

​
Step 3 (alternative) — Use gemini mcp add

Gemini CLI ships a command that writes the same block: 
gemini mcp add --transport http \
  --header "Authorization: Bearer $XYSQ_API_KEY" \
  xysq https://api.xysq.ai/mcp

​
Step 4 — Verify

gemini mcp list
You should see xysq listed with its connection status and available tools.

​
Step 5 — Use It

Start a Gemini CLI session: 
gemini
Try memory-aware prompts: 
Remember that I prefer TypeScript strict mode.
What's my current project context?
By default Gemini CLI prompts before each tool call. You can approve per-tool, per-server, or set "trust": true on the server entry to skip approvals (use cautiously — only for fully trusted servers): 
{
  "mcpServers": {
    "xysq": {
      "httpUrl": "https://api.xysq.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${XYSQ_API_KEY}"
      },
      "trust": true
    }
  }
}

​
Pinning Gemini to a team vault

To scope Gemini to a specific team, change the URL: 
{
  "mcpServers": {
    "xysq-acme": {
      "httpUrl": "https://api.xysq.ai/mcp/team/YOUR_TEAM_ID",
      "headers": {
        "Authorization": "Bearer ${XYSQ_API_KEY}"
      }
    }
  }
}
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.

​
Troubleshooting

ProblemFix
gemini mcp list doesn’t show xysqConfirm mcpServers is at the top level of ~/.gemini/settings.json and the JSON is valid.
url doesn’t work but httpUrl doesCorrect. url is for the deprecated SSE transport. Use httpUrl for xysq.
Auth fails with 401Confirm XYSQ_API_KEY is exported in the shell running gemini.
Approval prompts on every callSet "trust": true on the xysq entry — only if you’re comfortable skipping confirmations.
Wrong vault scopeConfirm the URL — /mcp for personal, /mcp/team/<id> for a team.

​
Next: install the Skill

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