# MCP client configuration

For an existing console account, use Extrovert's hosted, stateless Streamable HTTP endpoint when the
client supports OAuth:

```text
https://mcp.extrovert.dev/mcp
```

OAuth-capable clients discover the authorization server, open browser sign-in and consent, and store
and refresh the grant. No Extrovert key goes in the client configuration.

For local stdio, use an existing agent key or redeem an enrollment key. The packaged server stores the
durable agent key in a permission-restricted credential file. Free self-signup is currently paused, so
do not use `sign_up` as the initial connection path unless `GET /v1/signup-status` reports enabled.
**Hosted MCP permissions:** The OAuth connection is pinned to the signed-in user's default project. Owners, admins, and members
  receive inbox create, read, send, webhook, and commerce request permissions. Viewers and billing
  members receive read and commerce request permissions. Hosted MCP also accepts a limited
  `pk_agent_...` bearer credential and rejects `pk_enroll_...` enrollment keys.
**Try it with zero setup:** Drop `EXTROVERT_API_KEY` and add `"EXTROVERT_MOCK": "1"` to any snippet below. The server boots against
  deterministic fixtures, so you can click through every tool: including `wait_for_email`: fully
  offline, no key, no network.

## Run the package

Requires Node ≥ 20.

```bash frame="terminal"
# stdio: for local hosts
npx -y @extrovert.dev/mcp@next

# CLI/setup commands from the same package
npx -y @extrovert.dev/mcp@next --help

# self-hosted: stateless MCP Streamable HTTP at /mcp (default :8787)
npx -y @extrovert.dev/mcp@next --http --port 8787
```

## Codex

Install the complete plugin, which includes nine skills and the packaged stdio MCP server:

```bash frame="terminal"
codex plugin marketplace add extrovert-dot-dev/extrovert-skills
codex plugin add extrovert@extrovert
```

Start a new Codex session. If setup received an enrollment key, call `redeem_enrollment`; the packaged
server stores the returned agent key and the next session starts authenticated.

To configure only MCP, without the skills bundle:

```bash frame="terminal"
npx -y @extrovert.dev/mcp@next setup --host codex
```

For a human-owned console account, use hosted OAuth instead:

```bash frame="terminal"
codex mcp add extrovert --url https://mcp.extrovert.dev/mcp
codex mcp login extrovert
```

## Claude Desktop

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

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "extrovert": {
      "command": "npx",
      "args": ["-y", "@extrovert.dev/mcp@next"]
    }
  }
}
```

Running from a local checkout instead of npm:

```json title="claude_desktop_config.json (local checkout)"
{
  "mcpServers": {
    "extrovert": {
      "command": "node",
      "args": ["/absolute/path/to/extrovert/mcp/dist/bin.js"]
    }
  }
}
```

## Claude Code

Add the hosted endpoint, then use `/mcp` inside Claude Code to complete the browser OAuth flow:

```bash frame="terminal"
claude mcp add --transport http extrovert https://mcp.extrovert.dev/mcp
```

For local stdio instead:

```bash frame="terminal"
npx -y @extrovert.dev/mcp@next setup --host claude
```

Or connect to a deployment you operate over HTTP (pass your limited key as a bearer header):

```bash frame="terminal"
claude mcp add --transport http extrovert https://your-mcp-host.example/mcp \
  --header "Authorization: Bearer pk_agent_…"
```

## Cursor

`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "extrovert": {
      "command": "npx",
      "args": ["-y", "@extrovert.dev/mcp@next"]
    }
  }
}
```

  ```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "extrovert": {
      "url": "https://mcp.extrovert.dev/mcp"
    }
  }
}
```

  ## What key to use

Use OAuth for the hosted endpoint. The packaged stdio server loads a limited agent key from the local
credential store and writes the full replacement after `verify_signup` or `redeem_enrollment`.
`EXTROVERT_API_KEY` remains an explicit override. Never provide an org-wide credential. See
[Authentication & keys](https://docs.extrovert.dev/quickstart/authentication/).

On Linux and macOS the default file is `~/.config/extrovert/credentials.json` (or
`$XDG_CONFIG_HOME/extrovert/credentials.json`); Windows uses
`%APPDATA%\Extrovert\credentials.json`. The directory is owner-only and the file is mode `0600` on
Unix. Override the directory with `EXTROVERT_CONFIG_DIR` for an isolated or managed runtime.
**Do not put an administrative key in host config:** Host config files are easy to leak (synced dotfiles, screen shares, support bundles). Prefer the
  credential store or hosted OAuth. If an explicit key is required, use a limited agent key and rotate
  it if exposed. Pass an enrollment key only to the packaged local server for redemption, never to
  hosted MCP.

## Next

- [MCP overview & tools](https://docs.extrovert.dev/mcp/overview/): the full tool list and security model.
- [wait_for_email](https://docs.extrovert.dev/mcp/wait-for-email/): the blocking primitive.
- [Authentication and keys](https://docs.extrovert.dev/quickstart/authentication/): permissions and key reach.