# Connect Claude, ChatGPT, Cursor or Codex

Add the Assent MCP server to Claude Code, Claude Desktop, ChatGPT, Cursor or Codex, on macOS, Windows or Linux, and check it works.

Each assistant connects to the Assent MCP server as its own agent, so its asks carry its name and your rules can treat it on its own. The server is at:

```text
https://ordia-api.specvista.com/api/v1/mcp
```

It speaks Streamable HTTP and keeps no session. Claude (on the web, the desktop app and mobile), ChatGPT, Cursor and Claude Code can sign in with OAuth, so you never paste a key. Every other assistant authenticates with an agent key sent as `Authorization: Bearer <key>`.

## Before you start

1. In Assent, open **Agents**, choose **Add agent**, and name it after the assistant, for example `Claude Code` or `Cursor`.
2. Copy the agent key. It starts with `oak_` and Assent shows it once. Rotate it from the agent's settings if it leaks.
3. Keep the key out of files you commit. The examples below read it from the `ASSENT_AGENT_KEY` environment variable or from a private config file.

Set the variable in the shell you start the assistant from:

```bash
export ASSENT_AGENT_KEY=oak_...
```

In PowerShell, `$env:ASSENT_AGENT_KEY = "oak_..."` sets it for that window, and `setx ASSENT_AGENT_KEY oak_...` keeps it for new windows.

## Claude Code

```bash
claude mcp add --transport http assent https://ordia-api.specvista.com/api/v1/mcp --header "Authorization: Bearer $ASSENT_AGENT_KEY"
```

In PowerShell, write `$env:ASSENT_AGENT_KEY` in place of `$ASSENT_AGENT_KEY`. The shell fills in the key, so Claude Code stores it in its own MCP settings; keep those private. Run `claude mcp list` and check that `assent` is connected. To have risky tool calls wait for your answer too, add the [Claude Code hook](https://docs.specvista.com/assent/claude-code.md).

To sign in with OAuth instead of a key, run `claude mcp add --transport http assent https://ordia-api.specvista.com/api/v1/mcp`, then run `/mcp` in Claude Code, pick assent and choose Authenticate. Assent opens in your browser; the page warns that it returns to a program on this computer, so choose Allow only if you just started this yourself.

## Claude Desktop

Claude Desktop starts local MCP servers from its config file: `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Add:

```json
{
  "mcpServers": {
    "assent": {
      "command": "npx",
      "args": ["-y", "assent-cli@latest", "mcp"],
      "env": { "ASSENT_AGENT_KEY": "oak_..." }
    }
  }
}
```

Restart Claude Desktop. `assent mcp` reads MCP messages on stdin and forwards each one to the server above with the key. To skip the key, add Assent as a custom connector instead: in Claude, open Settings, then Connectors, choose Add custom connector, paste `https://ordia-api.specvista.com/api/v1/mcp`, leave the advanced OAuth settings empty, choose Connect and then Allow. This works in Claude on the web, the desktop app and mobile.

## ChatGPT

ChatGPT adds Assent as a custom connector and signs in with OAuth, so you never paste a key. Everything it does shows up under one agent named **ChatGPT** (or **ChatGPT connector** if you already have an agent called ChatGPT).

1. In a workspace, an admin first allows developer mode or custom connectors under **Workspace settings**, **Permissions & roles**. OpenAI renames these menus between rollouts, so look for the closest match.
2. In ChatGPT, open **Settings**, **Apps** (or **Connectors**), **Advanced settings**, and turn on **Developer mode**.
3. Choose **Create app** (or **Create**) and fill in:
   - Name: `Assent`
   - MCP server URL: `https://ordia-api.specvista.com/api/v1/mcp`
   - Authentication: **OAuth**, leaving the client ID and secret empty. ChatGPT registers itself.
4. Tick that you trust the app and choose **Create**.
5. ChatGPT opens Assent. Sign in if asked. The page reads **Allow ChatGPT?** and names the agent it will act as. Choose **Allow** within 10 minutes, in the same browser ChatGPT opened. You return to ChatGPT and it lists the Assent tools.

Never choose **Allow** on a link someone sent you: if you did not just start connecting, choose **Deny**. To disconnect, open the ChatGPT agent in Assent and rotate its key, which ends ChatGPT's sign-in so it has to connect again, or pause the agent to stop it for a while.

A scheduled task that cannot wait for you should call `assent_answers` at the start of each run, act on what it finds and mark each answer with `assent_picked_up`, then ask with `assent_ask` and leave the answer for the next run.

## Cursor

Add the server to `~/.cursor/mcp.json`, or `.cursor/mcp.json` in one project (on Windows, `%USERPROFILE%\.cursor\mcp.json`):

```json
{
  "mcpServers": {
    "assent": {
      "url": "https://ordia-api.specvista.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${env:ASSENT_AGENT_KEY}" }
    }
  }
}
```

Start Cursor from a shell where `ASSENT_AGENT_KEY` is set, or put the key in place of `${env:ASSENT_AGENT_KEY}` in a file you never commit. Open **Cursor Settings**, **MCP** and check that `assent` shows its tools.

## Codex

Codex starts MCP servers as local commands. Save the agent key in a private config file first:

```bash
mkdir -p ~/.assent
echo '{ "agentKey": "oak_..." }' > ~/.assent/codex.json
chmod 600 ~/.assent/codex.json
```

On Windows, in PowerShell:

```powershell
New-Item -ItemType Directory -Force "$HOME\.assent" | Out-Null
Set-Content -Encoding ascii -Path "$HOME\.assent\codex.json" -Value '{ "agentKey": "oak_..." }'
```

Use `-Encoding ascii`. In Windows PowerShell 5, `-Encoding utf8` adds a byte order mark and `>` writes UTF-16, and the command line rejects both. Then add to `~/.codex/config.toml` (`%USERPROFILE%\.codex\config.toml` on Windows):

```toml
[mcp_servers.assent]
command = "npx"
args = ["-y", "assent-cli@latest", "mcp"]
env = { ASSENT_CONFIG = "/Users/you/.assent/codex.json" }
```

On Windows, use the full path with doubled backslashes, such as `"C:\\Users\\you\\.assent\\codex.json"`, and if Codex cannot start the server, set `command = "npx.cmd"`. Start a new Codex session and ask it to list its Assent tools.

## Check it works

Ask the assistant to call `assent_ask` with a small approval, for example a title of `Try Assent?` and a why of `Checking the connection`, then `assent_wait_for_answer`. The ask appears in your inbox; approve it and the assistant sees `answer.actionId` `done`. Then ask it to call `assent_picked_up` with the ask's uuid, so the answer is never delivered again.

## Common problems

| What you see | What to do |
|---|---|
| `401` or "Agent key required" | The key is missing or not sent as a bearer token. Check the variable is set in the shell that started the assistant. |
| `401` after it worked before | The key was rotated or the agent removed. Copy the new key from the agent's settings. |
| `assent mcp` exits with code 5 | It found no agent key, or the config file is not plain JSON. Set `ASSENT_AGENT_KEY`, or point `ASSENT_CONFIG` at a file holding `{ "agentKey": "oak_..." }` saved without a byte order mark. |
| `invalid_redirect_uri` when connecting ChatGPT | ChatGPT's return address changed. Email [hello@specvista.com](mailto:hello@specvista.com). |
| The consent page says the request expired | Start connecting again from ChatGPT, and finish in the same browser within 10 minutes. |
| `Too many waits at once for this agent or account` (status 429) | Each agent can wait on 4 asks at a time and each account on 10. Wait for one to finish, then try again. |

[MCP server](https://docs.specvista.com/assent/mcp.md) lists every tool and its arguments.