# Connect an AI client

Configuration for Claude Desktop, Claude Code, Cursor and generic MCP clients, plus how to verify the connection works.

> **Planned design**: The MCP server described here is the planned design layered on top of the agency REST gateway, which is live today. Until the server ships, everything on this page can be done with the REST endpoints in the API section.

## Before you start

1. **Create an API key**: In AgentixSEO go to Agency → Automations → API and create a key. Give it the `read` scope only for your first connection; you can create a second write-capable key later.
2. **Note which clients the key can reach**: A key is scoped to the clients you select. The assistant can only pass those `client_id` values.
3. **Store the key in your shell profile**: Keep it out of config files that sync or get committed.

   ```bash
export AGENTIX_API_KEY="agx_live_..."
   ```

## Client configuration

**Claude Desktop**

Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`), then restart Claude.

```json
{
  "mcpServers": {
    "agentixseo": {
      "command": "npx",
      "args": ["-y", "@agentixseo/mcp-server"],
      "env": {
        "AGENTIX_API_KEY": "agx_live_..."
      }
    }
  }
}
```

**Claude Code**

Add the server from the terminal. It is stored per project unless you pass `--scope user`.

```bash
claude mcp add agentixseo \
  --env AGENTIX_API_KEY=$AGENTIX_API_KEY \
  -- npx -y @agentixseo/mcp-server

claude mcp list
```

**Cursor**

Create `.cursor/mcp.json` in the project (or `~/.cursor/mcp.json` for every project), then reload the window.

```json
{
  "mcpServers": {
    "agentixseo": {
      "command": "npx",
      "args": ["-y", "@agentixseo/mcp-server"],
      "env": { "AGENTIX_API_KEY": "agx_live_..." }
    }
  }
}
```

**Hosted / HTTP**

Agents that cannot spawn a process connect over streamable HTTP and send the key as a header.

```json
{
  "mcpServers": {
    "agentixseo": {
      "type": "http",
      "url": "https://mcp.agentixseo.com/v1",
      "headers": { "X-API-Key": "agx_live_..." }
    }
  }
}
```

## Verify the connection

1. **Check the tool list**: Ask the assistant "what AgentixSEO tools do you have?". It should list the read tools, and write tools only if your key has the `write` scope.
2. **Run a harmless read**: Ask it to list your clients. This calls `list_clients`, which needs nothing but a valid key.
3. **Confirm scoping**: Ask for a client the key should not reach. The gateway returns 403 and the assistant should report that it has no access rather than inventing an answer.

## Common problems

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| No AgentixSEO tools appear | Config file not reloaded, or JSON is invalid | Validate the JSON and fully quit and reopen the client, a window reload is not always enough. |
| Every call returns 401 | Key missing from `env`, or the key was revoked | Re-create the key and confirm the env var is set in the process that launches the server. |
| Only read tools appear | Key has the `read` scope | Create a key with `write` (or `*`) and point the client at it. |
| 403 on a specific client | Key is not scoped to that client | Edit the key in Agency → Automations → API and add the client. |
| Calls time out on long jobs | Audits and article generation are asynchronous | The tool returns a job reference; poll the matching read tool instead of waiting. |