# Connect your agent with npx seofix connect

> One command adds the SEOFix MCP server to Claude Code, Codex and Cursor. You approve it in the browser, pick a team, and the CLI writes the config.

Source: https://seofix.ai/help/connect-your-agent · Category: AI agents & MCP · Updated: 2026-10-08

Run `npx seofix connect` in your project folder. It shows a code, opens `https://seofix.ai/connect`, and after you approve it there it creates an API key for the team you pick and adds the SEOFix MCP server (`https://mcp.seofix.ai/mcp`) to Claude Code, Codex and Cursor. Then restart your agent.

```bash
npx seofix connect
```

It needs Node.js 20 or newer. You never copy or paste the API key.

## Steps

1. Run `npx seofix connect` in a terminal, in the project folder you want Cursor configured for.
2. The CLI prints a code like `ABCD-EFGH` and opens `https://seofix.ai/connect?code=ABCD-EFGH` in your browser. If the browser does not open, open the printed link yourself.
3. Sign in to SEOFix if you are not signed in.
4. On the **Connect your agent** page, check the request: the machine name and agents, when it was made, and where from (country, or a masked IP address). Approve only if you ran the command yourself just now.
5. Confirm that the code on the page matches your terminal. When you arrived through the link, tick **The code ... matches the one in my terminal**.
6. Pick the **Team**. The key acts for that team only.
7. Click **Approve**. The page shows **Agent connected**. Click **Deny** instead if you did not start the request; the CLI then stops without changing anything.
8. Back in the terminal, the CLI prints `Approved for team <name>.` and configures each agent.
9. Restart your agent and ask it to audit your site with SEOFix.

The code expires after 10 minutes. The CLI polls the API every 5 seconds until you approve, deny, or the code expires. If it expires, run the command again for a new code.

If you open `https://seofix.ai/connect` without the link, type the 8-character code from your terminal and click **Continue**.

## What it configures

By default the CLI configures every agent it finds on the machine:

| Agent | Detected when |
| --- | --- |
| Claude Code | the `claude` CLI is on your `PATH` |
| Codex | the `codex` CLI is on your `PATH`, or `~/.codex` (or `$CODEX_HOME`) exists |
| Cursor | the `cursor` CLI is on your `PATH`, or `~/.cursor` or `./.cursor` exists |

If none is found, the CLI stops and asks you to pick one with `--agent`.

### Claude Code

The CLI removes any existing user-scope `seofix` server and runs:

```bash
claude mcp add --scope user --transport http seofix https://mcp.seofix.ai/mcp --header "Authorization: Bearer sk_..."
```

The server is added at user scope, so it is available in every project. If the `claude` CLI is not on your `PATH`, or the command fails, the CLI prints the command for you to run instead. The key in that printed command is hidden (`sk_xxxx…`) unless you pass `--print`.

### Codex

The CLI writes or updates the `[mcp_servers.seofix]` table in `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`). Every other line of the file, comments included, is left as it was.

```toml
[mcp_servers.seofix]
url = "https://mcp.seofix.ai/mcp"
http_headers = { "Authorization" = "Bearer sk_..." }
```

### Cursor

The CLI writes or merges `mcpServers.seofix` into `.cursor/mcp.json` in the current folder. Other servers in the file are kept.

```json
{
  "mcpServers": {
    "seofix": {
      "url": "https://mcp.seofix.ai/mcp",
      "headers": {
        "Authorization": "Bearer sk_..."
      }
    }
  }
}
```

That file holds your API key, so the CLI protects it:

- Inside a git work tree, it adds `/.cursor/mcp.json` and `/.cursor/mcp.json.bak` to `.git/info/exclude`, so git ignores them.
- If `.cursor/mcp.json` is already committed to git, the CLI refuses to write the key into it. Untrack it (`git rm --cached .cursor/mcp.json`) and run again, or pass `--force` if you really want the key in a tracked file.
- If `.cursor` or `mcp.json` is a symlink that leads outside the current folder, the CLI refuses to write.
- If `.cursor/mcp.json` is not valid JSON, the CLI stops and asks you to fix or remove it.

### Files and backups

- Before changing a file, the CLI copies the previous version to `<file>.bak`.
- Files that hold the key (and their backups) are written with mode `0600`.
- A file whose content would not change is left alone.

## Options

```text
npx seofix connect [--agent claude|codex|cursor|all] [--api URL] [--print] [--no-browser] [--force]
npx seofix status
```

| Option | What it does |
| --- | --- |
| `--agent` | Which agents to configure: `claude`, `codex`, `cursor` or `all`. Default: the ones detected on this machine. |
| `--api` | API base URL. Default `https://api.seofix.ai`, or `$SEOFIX_API_URL` when set. |
| `--print` | Also print the new API key (and the full `claude mcp add` command). The key is never shown otherwise. |
| `--no-browser` | Do not open the browser; open the printed link yourself. |
| `--force` | Write `.cursor/mcp.json` even when git tracks it. Your key would then be in a committed file. |
| `--help`, `--version` | Usage and CLI version. |

`npx seofix status` lists which agents have SEOFix configured (Claude Code via `claude mcp get seofix`, Codex in `config.toml`, Cursor in `./.cursor/mcp.json` then `~/.cursor/mcp.json`). It never prints keys.

## The key it creates

- The key is labelled with the machine and agents. Settings → Agent & MCP → Connected agents shows it as `seofix connect on <hostname> · <agents>`, for example "seofix connect on macbook · claude, cursor".
- It acts for the team you picked on the approval page, and only while you are still a member of that team.
- Connected agents lists it with its prefix, team, creation date and when it was last used. Click **Revoke** there to disable it immediately.
- It is separate from the key you create in Settings: rotating the Settings key does not affect it.

The key exists in plain text only in the one response the CLI receives. SEOFix stores only a hash. See [API keys](https://seofix.ai/help/api-keys.md).

## Running it again

Running `npx seofix connect` again is safe:

- Config entries are replaced, never duplicated.
- Connecting the same agents on the same machine to the same team replaces their previous key. The old key stops working.
- Connecting a different set of agents, or picking a different team, creates a separate key. The earlier key keeps working until you revoke it.

To rotate a CLI key, run `npx seofix connect` again with the same agents and team, or revoke it in Settings and connect again.

## Windows

The CLI works on Windows. Two differences:

- It opens the browser with `rundll32`. If that fails, open the printed link yourself.
- If `claude` on your `PATH` is a `.cmd` or `.bat` shim, the CLI cannot run it (it never uses a shell). It prints the `claude mcp add` command instead. Run `npx seofix connect --agent claude --print` to see the command with the key, then run it yourself.

## Troubleshooting

| Message | What to do |
| --- | --- |
| `No supported agent found` | Install the agent, or name it: `--agent claude`, `codex`, `cursor` or `all`. |
| `The code expired.` | Run `npx seofix connect` again. Approve within 10 minutes. |
| `The request was denied in the browser.` | Someone clicked **Deny**. Nothing was changed. Run the command again. |
| `Couldn't reach https://api.seofix.ai` | Check your network connection and try again. |
| `Unexpected response ... Is --api correct?` | Remove `--api` or `SEOFIX_API_URL`, or point it at the right API. |
| `.cursor/mcp.json is committed to git` | Untrack the file, or use `--force` knowingly. |

Starting the flow is limited to 10 requests per hour per IP address.

## Related

- [Set up the MCP server by hand](https://seofix.ai/help/mcp-server.md)
- [MCP tools reference](https://seofix.ai/help/mcp-tools-reference.md)
- [Agent playbook](https://seofix.ai/help/agent-playbook.md)
- [API keys](https://seofix.ai/help/api-keys.md)