> ## Documentation Index
> Fetch the complete documentation index at: https://docs.use.observer/llms.txt
> Use this file to discover all available pages before exploring further.

# Install in your client

> Add the Observer MCP server to Claude, Claude Code, Cursor, VS Code, Codex, Gemini CLI or another MCP client. Sign in with OAuth; no API key to paste.

The server URL is `https://mcp.use.observer/mcp`. Add it with no header: the
first time the client connects, it opens Observer's sign-in and approval page
in your browser. An owner of the organization approves the scopes, and the
client receives its own tokens. See [Connect with OAuth](/docs/mcp/oauth) for
what happens during sign-in.

For a connection that can only read, use
`https://mcp.use.observer/mcp/readonly` in place of the URL below. See
[Endpoints](/docs/mcp/index#endpoints) for the other views.

> [!NOTE]
>
> **Plan**
>
> The MCP server runs on the public API, which starts on the Starter plan. An
> organization on Free gets a one-time 14-day Starter trial when it first
> approves a connection.

## Add the server

**Claude**

On Free, Pro and Max plans (claude.ai, Claude Desktop):

1. Open **Customize** > **Connectors**.
2. Select **+ Add** > **Add custom connector**.
3. Enter the name `Observer` and the URL `https://mcp.use.observer/mcp`, then
   select **Continue**.
4. Review the detected authentication and select **Add**. Approve the
   connection in the browser when Observer's sign-in page opens.

The Free plan allows one custom connector.

On Team and Enterprise plans, an owner adds the connector for the
organization first: **Organization settings** > **Connectors** > **Add**,
hover over **Custom** and select **Web**, then enter the name and URL. On Team,
this needs an Owner or Primary Owner. On Enterprise, an Owner, a Primary Owner
or a custom role with "Manage access to Libraries". Members then connect
under **Customize** > **Connectors** > **Connect**.

**Claude Code**

```bash theme={null}
claude mcp add --transport http observer https://mcp.use.observer/mcp
```

The default scope is `local`: the server is available to you in the current
project only. Add `--scope user` to use it in every project, or
`--scope project` to write it to `.mcp.json` in the repository and share it:

```json title=".mcp.json" theme={null}
{
  "mcpServers": {
    "observer": { "type": "http", "url": "https://mcp.use.observer/mcp" }
  }
}
```

To sign in, run `/mcp` in a session and choose **observer**, or run
`claude mcp login observer` from the shell.

To get the [agent skills](/docs/mcp/skills) as well, install the Observer
plugin instead. It adds the same server with OAuth:

```text theme={null}
/plugin marketplace add useobserver/skills
/plugin install observer@useobserver
```

From the shell:

```bash theme={null}
claude plugin marketplace add useobserver/skills
claude plugin install observer@useobserver
```

On Claude Code 2.1.275 or later, the plugin also installs in one step with
`/plugin install observer --marketplace useobserver/skills`, which asks you to
confirm the marketplace. The shell form,
`claude plugin install observer --marketplace useobserver/skills`, needs
2.1.292 or later. Then run `/mcp`, choose **observer** and sign in.

**Cursor**

Open this link to add the server with OAuth:

```text theme={null}
cursor://anysphere.cursor-deeplink/mcp/install?name=observer&config=eyJ1cmwiOiJodHRwczovL21jcC51c2Uub2JzZXJ2ZXIvbWNwIn0=
```

The `config` value is the base64 of `{"url":"https://mcp.use.observer/mcp"}`.

Or add the server under `mcpServers` in `~/.cursor/mcp.json` (every project)
or `.cursor/mcp.json` (one project):

```json title="~/.cursor/mcp.json" theme={null}
{
  "mcpServers": {
    "observer": { "url": "https://mcp.use.observer/mcp" }
  }
}
```

**VS Code**

With GitHub Copilot in VS Code, run:

```bash theme={null}
code --add-mcp '{"name":"observer","type":"http","url":"https://mcp.use.observer/mcp"}'
```

Or open this link (for VS Code Insiders, replace `vscode:` with
`vscode-insiders:`):

```text theme={null}
vscode:mcp/install?%7B%22name%22%3A%22observer%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.use.observer%2Fmcp%22%7D
```

Or add the server under `servers` in `.vscode/mcp.json`:

```json title=".vscode/mcp.json" theme={null}
{
  "servers": {
    "observer": { "type": "http", "url": "https://mcp.use.observer/mcp" }
  }
}
```

The key is `servers`, not `mcpServers`. VS Code opens the sign-in in your
browser the first time it connects.

**Codex**

```bash theme={null}
codex mcp add observer --url https://mcp.use.observer/mcp
codex mcp login observer
```

Or add the server to `~/.codex/config.toml`, then run
`codex mcp login observer`:

```toml title="~/.codex/config.toml" theme={null}
[mcp_servers.observer]
url = "https://mcp.use.observer/mcp"
```

**Gemini CLI**

```bash theme={null}
gemini mcp add --transport http observer https://mcp.use.observer/mcp
```

The default scope is `project`. Add `-s user` to use the server in every
project. Then run `/mcp auth observer` in a session. Sign-in opens a browser
on the machine running Gemini CLI, so it does not work in a headless session
or over SSH.

Or add the server under `mcpServers` in `settings.json`. The URL goes in
`httpUrl`:

```json title="settings.json" theme={null}
{
  "mcpServers": {
    "observer": { "httpUrl": "https://mcp.use.observer/mcp" }
  }
}
```

The Observer extension adds the same server and loads the
[agent skills](/docs/mcp/skills):

```bash theme={null}
gemini extensions install https://github.com/useobserver/skills
```

On the unpaid tier and with Google One plans, Antigravity CLI replaced Gemini
CLI on 2026-06-18.

**Other clients**

Add a remote server that speaks Streamable HTTP, with the URL and no header:

```json title="MCP client config" theme={null}
{
  "mcpServers": {
    "observer": { "url": "https://mcp.use.observer/mcp" }
  }
}
```

Config shapes vary by client. Some expect a `"type": "http"` field alongside
the `url`. Check your client's remote MCP documentation.

## Confirm the connection

Ask the assistant which Observer organization it is connected to. It calls
`getMe` and reports the organization, the scopes it holds, your plan, quotas
and rate limits.

## Without OAuth

A client without OAuth support can send an `obs_pub_` API key as
`Authorization: Bearer <key>`. Create the key under **Developers** >
**API keys** with only the scopes you need, or let the assistant request one
through [Connect an AI agent](/docs/mcp/connect-ai-agent), which also shows
the key configuration for each client. Keep keys out of files you commit: use
user-level config or an environment variable reference.

## Skills for any client

Clients that read Agent Skills (Cursor, Codex, Copilot, OpenCode and others)
can install the skills on their own. Add the MCP server separately, as above:

```bash theme={null}
npx skills add useobserver/skills
npx skills add useobserver/skills --skill observer-setup   # one skill only
```

See [Agent skills](/docs/mcp/skills).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.