> ## 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.

# Connect with OAuth

> Add the Observer MCP server to a client that supports MCP authorization. The client opens a browser, an owner approves the scopes, and no API key is pasted anywhere.

MCP clients that implement the MCP authorization spec can connect to the
[Observer MCP server](/docs/mcp/index) with OAuth. You add the server URL
with no header. The client opens a browser, you sign in to Observer and
approve the request, and the client receives its own tokens. You never copy
a key into a config file.

Clients without OAuth support keep working with an API key. See
[API keys still work](#api-keys-still-work).

## Add the server

Add `https://mcp.use.observer/mcp` to your client with no `Authorization`
header.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http observer https://mcp.use.observer/mcp
    ```

    Then run `/mcp` in Claude Code and choose **observer** to sign in.
  </Tab>

  <Tab title="Other clients">
    ```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.
  </Tab>
</Tabs>

## Approve the connection

<Steps>
  <Step title="The client opens a browser">
    On its first request without a token, the server answers `401` and points
    the client at Observer's authorization server. The client registers itself
    and opens `https://use.observer/oauth/authorize` in your browser.
  </Step>

  <Step title="Sign in and choose the organization">
    Sign in to Observer. If you belong to several organizations, choose the one
    the client should work in.
  </Step>

  <Step title="Review and approve the scopes">
    The page names the application and lists each scope it asks for in plain
    language. Scopes that act on what your customers see or receive (writing
    incidents, maintenance windows, or manual metric status) are marked. The page also
    shows the address the client returns to. Select **Approve** to connect, or
    **Deny** to refuse.
  </Step>

  <Step title="Return to the client">
    The browser hands control back to the client, which can now call tools.
    Ask it to call `getMe` to confirm the organization, scopes, and plan.
  </Step>
</Steps>

Only an **owner** of the organization can approve, because approving
creates an API key for the organization. A member who is not an owner is
asked to send the request to an owner.

The MCP server runs on the public API, which starts on Starter. As with
[Connect an AI agent](/docs/mcp/connect-ai-agent#starter-trial), approving
from an organization on Free starts a 14-day Starter trial if the
organization has not used one. Otherwise the page asks you to upgrade.

## Scopes

OAuth uses the same scopes as API keys. See
[Authentication](/api/getting-started/auth) for the full list.

When a client asks for no particular scopes, the request covers the same
preset as [Connect an AI agent](/docs/mcp/connect-ai-agent#access-preset):
setting up status pages, services, metrics, SLOs and Observer Agents, plus
read access to incidents. It does not include incident, maintenance or
manual status writes.

If a tool needs a scope the connection does not have, the server answers
`403` with `insufficient_scope` and names every missing scope. Clients that
support step-up authorization open the approval page again for the extra
scopes. Other clients show the error, and you reconnect with the scopes you
want.

## Tokens

Access tokens last one hour. The client refreshes them on its own: every
refresh returns a new refresh token, and the old one stops working. If a
used refresh token is presented again, Observer revokes the whole
connection, and the client has to be approved again.

## Revoke a connection

Each approval appears as an API key named after the client, for example
`Claude Code (MCP OAuth)`, under **Settings** > **API keys**. Revoke that key
to disconnect the client. Its next call fails, and connecting again needs a
new approval.

## API keys still work

An `obs_pub_` API key sent as `Authorization: Bearer <key>` works exactly
as before. Use it for clients without OAuth support, for scripts, or when
you want a key with a fixed scope set. Create one under **Settings** >
**API keys**, or let an agent request one through
[Connect an AI agent](/docs/mcp/connect-ai-agent).

Either way, the API checks the token or key on every call: a missing scope
returns `403`, a plan without public API access returns `403`, and rate
limits return `429` with a retry hint.


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