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

# Setup

> Add the Ravenna MCP server to ChatGPT, Claude, Cursor, VS Code, Windsurf, and other AI clients using OAuth sign-in or a workspace API key.

Connect your AI assistant to Ravenna by adding the MCP server to your client's configuration. All requests go through a single endpoint: `https://core.ravenna.ai/mcp`.

Authenticate using OAuth sign-in. Your client redirects you to sign in to Ravenna with your existing account. No API keys needed.

***

## Sign in with OAuth

OAuth-capable MCP clients discover Ravenna's authorization server automatically from the MCP endpoint. When you add the server, your client opens a browser window for you to sign in to Ravenna. After sign-in, the client receives an access token scoped to your user and organization, and uses it for every MCP request.

**When to use OAuth:**

* Your MCP client supports OAuth (for example, ChatGPT or the latest versions of Claude and Cursor).
* You want to authenticate as yourself rather than share a workspace-level API key.
* You do not have permission to create API keys in your workspace.

**How to connect:**

**1. Add the MCP server URL**

In your client's MCP settings, add a server pointing to `https://core.ravenna.ai/mcp`. Do not set an `Authorization` header. Your client handles the token automatically once OAuth completes.

**2. Complete the sign-in flow**

Your client opens a browser window to Ravenna's sign-in page. Authenticate with your Ravenna account, then approve the connection. The browser window closes automatically when sign-in completes.

**3. Verify the connection**

Return to your client and ask your assistant to list its Ravenna tools. The tools become available immediately once the token is issued.

> [!TIP]
>
> OAuth tokens are scoped to your user account and the organization you sign in to. They grant access to all workspaces and data in that organization that your account has permissions to access. Your assistant can work across any of those workspaces in a single session. To use a different organization, see [Using MCP with multiple organizations](https://docs.ravenna.ai/documentation/automate/mcp/overview.md#using-mcp-with-multiple-organizations).

***

## Configure your AI client

### ChatGPT

ChatGPT connects to Ravenna using OAuth sign-in. You add the MCP server URL in ChatGPT's connector settings, then sign in to Ravenna in a browser pop-up. No API key required.

**Step 1**

In ChatGPT, open **Settings** → **Connectors** → **Add custom connector**.

**Step 2**

Fill in the details:

1. **Name:** `Ravenna`
2. **MCP Server URL:** `https://core.ravenna.ai/mcp`
3. Leave the authentication field set to OAuth.

**Step 3**

Click **Connect**. A browser window opens to Ravenna's sign-in page. Authenticate with your Ravenna account and approve the connection.

**Step 4**

Start a new ChatGPT conversation and ask it to list your Ravenna tools to confirm the connection.

> [!TIP]
>
> Your ChatGPT connection is scoped to your user account and grants access to all workspaces you have permissions for in the organization you signed in to. Specify which workspace you want to work with when prompting your assistant.

***

### Claude Code

Claude Code supports OAuth authentication for MCP servers. A single terminal command registers the Ravenna server and initiates the OAuth flow.

**1. Add the MCP server**

Run the command below in your terminal. The `--callback-port 56567` option is critical for the OAuth callback.

```bash Terminal theme={"system"}
claude mcp add ravenna \
  --transport http \
  https://core.ravenna.ai/mcp \
  --callback-port 56567
```

> [!TIP]
>
> Use the built-in HTTP connection shown here, not `mcp-remote`. If you already run `mcp-remote` from Claude Code, switch to this command. The built-in connection reconnects automatically after Ravenna updates its tools. `mcp-remote` needs a manual reconnect, and signs in on a random port unless you pin it to `56567`.

**2. Complete OAuth sign-in**

Your browser will open automatically for you to sign in to Ravenna. Authenticate with your Ravenna account and approve the connection. The browser window closes automatically when sign-in completes.

**3. Start a new session**

Open a new Claude Code session. The Ravenna tools will be available automatically.

**4. Verify the connection**

Ask Claude Code to list your Ravenna channels to confirm the connection works. You can also run `/mcp` to check the server status.

> [!TIP]
>
> Your OAuth token is scoped to your user account and grants access to all workspaces you have permissions for in the organization you signed in to. You can work across any of your workspaces in a single session.

Learn more about [MCP servers in Claude Code](https://code.claude.com/docs/en/mcp)

***

### Codex

Codex supports OAuth authentication for MCP servers. Configuration is stored in a `config.toml` file.

**1. Open your config file**

Codex reads MCP configuration from `config.toml` in your Codex home directory. Create the file if it does not exist.

* **macOS and Linux:** `~/.codex/config.toml`
* **Windows:** `%USERPROFILE%\.codex\config.toml`

If you set the `CODEX_HOME` environment variable, Codex uses `$CODEX_HOME/config.toml` instead.

**2. Add the MCP server configuration**

Add the following to your `config.toml`. Place `mcp_oauth_callback_port` at the top of the file, above any `[table]` headers, so Codex reads it as a global setting.

```toml config.toml theme={"system"}
# Fixed OAuth callback port. Ravenna only accepts callbacks on port 56567.
mcp_oauth_callback_port = 56567

[mcp_servers.ravenna]
url = "https://core.ravenna.ai/mcp"
```

With this setting, Codex sends the sign-in callback to `http://127.0.0.1:56567/callback/R1_hNylnFZtJ`. The last part of the path is an ID that Codex derives from the server URL, so it is the same for everyone who connects to `https://core.ravenna.ai/mcp`. Ravenna's sign-in page only accepts callbacks on port `56567`. If Codex picks a random port, sign-in fails with a `Callback URL mismatch` error.

**3. Authenticate with OAuth**

Run the login command to initiate the OAuth flow:

```bash Terminal theme={"system"}
codex mcp login ravenna
```

Your browser opens automatically. Sign in to Ravenna and approve the connection.

**4. Verify the connection**

Start Codex and ask it to list your Ravenna channels to confirm the connection works.

> [!TIP]
>
> The OAuth callback port setting is shared across all MCP servers in Codex. If you connect to multiple OAuth-based MCP servers, they all use port 56567.

> [!WARNING]
>
> If sign-in fails with `Callback URL mismatch`, check the `redirect_uri` in the error message or the browser address bar. It should be `http://127.0.0.1:56567/callback/R1_hNylnFZtJ` or `http://localhost:56567/callback/R1_hNylnFZtJ`. See **Callback URL mismatch** under [Troubleshooting](#troubleshooting) for fixes.

Learn more about [MCP servers in Codex](https://developers.openai.com/codex/mcp)

***

### OpenCode

OpenCode supports OAuth authentication for remote MCP servers. Configuration is stored in an `opencode.json` file.

**1. Open your config file**

OpenCode reads MCP configuration from `opencode.json`. Create the file if it does not exist.

* **Global (all projects):** `~/.config/opencode/opencode.json`
* **Single project:** `opencode.json` in the project root

**2. Add the MCP server configuration**

Add the following to your `opencode.json`:

```json opencode.json theme={"system"}
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ravenna": {
      "type": "remote",
      "url": "https://core.ravenna.ai/mcp",
      "oauth": {
        "redirectUri": "http://127.0.0.1:56567/oauth/callback"
      }
    }
  }
}
```

OpenCode's default callback (port `19876`) is not accepted by Ravenna's sign-in page, so set `redirectUri` exactly as shown.

**3. Authenticate with OAuth**

Run the auth command to initiate the OAuth flow:

```bash Terminal theme={"system"}
opencode mcp auth ravenna
```

Your browser opens automatically. Sign in to Ravenna and approve the connection.

**4. Verify the connection**

Start OpenCode and ask it to list your Ravenna channels to confirm the connection works. If sign-in fails, run `opencode mcp debug ravenna` to see where the OAuth flow stops.

Learn more about [MCP servers in OpenCode](https://opencode.ai/docs/mcp-servers/)

***

### Claude Desktop

Claude Desktop can connect to Ravenna using the `mcp-remote` package, which bridges the remote HTTP MCP server to Claude Desktop's stdio-based MCP protocol.

**1. Locate your configuration file**

Claude Desktop stores MCP configuration in `claude_desktop_config.json`. The location depends on your platform:

* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

**2. Add the Ravenna MCP server**

Add the following configuration to your `claude_desktop_config.json`:

```json claude_desktop_config.json theme={"system"}
{
  "mcpServers": {
    "ravenna": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://core.ravenna.ai/mcp",
        "56567",
        "--host",
        "127.0.0.1"
      ]
    }
  }
}
```

**3. Restart Claude Desktop**

Restart Claude Desktop to load the new MCP server configuration.

**4. Complete OAuth sign-in**

When you first use the Ravenna MCP server, Claude Desktop will prompt an OAuth flow. Your browser will open automatically for you to sign in to Ravenna. Authenticate with your Ravenna account and approve the connection.

**5. Verify the connection**

Ask Claude to list your Ravenna tools to confirm the connection works.

> [!TIP]
>
> The `mcp-remote` package acts as a bridge, allowing Claude Desktop (which uses stdio-based MCP) to connect to HTTP-based MCP servers like Ravenna. Port 56567 is used for the OAuth callback flow.

***

### Cursor

Cursor supports OAuth authentication for MCP servers. Add the Ravenna server to `.cursor/mcp.json` and Cursor handles the OAuth sign-in flow automatically the first time you connect.

**1. Open the configuration file**

Create or edit `.cursor/mcp.json` in your project root. For global access across all projects, use `~/.cursor/mcp.json` in your home directory instead.

**2. Add the Ravenna MCP server**

Add the following configuration:

```json .cursor/mcp.json theme={"system"}
{
  "mcpServers": {
    "ravenna": {
      "url": "https://core.ravenna.ai/mcp"
    }
  }
}
```

Do not add an `Authorization` header. Cursor handles OAuth automatically once you sign in.

**3. Enable the server in Cursor settings**

Open **Cursor Settings** → **Tools & MCP**. Ravenna appears in the MCP servers list. Toggle it on if it is not already enabled.

**4. Complete OAuth sign-in**

The first time you use the server, Cursor opens a browser window to Ravenna's sign-in page. Authenticate with your Ravenna account and approve the connection.

**5. Verify the connection**

Ask Cursor to list your Ravenna channels to confirm the connection works.

> [!TIP]
>
> Your OAuth token is scoped to your user account and grants access to all workspaces you have permissions for in the organization you signed in to.

Learn more about [MCP servers in Cursor](https://cursor.com/docs/mcp)

***

### VS Code

VS Code supports OAuth authentication for MCP servers through GitHub Copilot. The OAuth callback URL is `http://127.0.0.1:33418/` and is automatically handled by VS Code.

**1. Create the configuration file**

Create a file called `.vscode/mcp.json` in your project root. For global access across all projects, add the configuration to your VS Code User Settings JSON instead.

**2. Add the Ravenna MCP server**

Add the following configuration to `.vscode/mcp.json`:

```json .vscode/mcp.json theme={"system"}
{
  "servers": {
    "ravenna": {
      "type": "http",
      "url": "https://core.ravenna.ai/mcp"
    }
  }
}
```

Note: Do not add an `Authorization` header. VS Code handles OAuth authentication automatically.

**3. Reload VS Code**

Reload the window or restart VS Code to load the new MCP server configuration.

**4. Complete OAuth sign-in**

When you first use the Ravenna MCP server, VS Code will prompt you to authenticate. Your browser will open automatically for you to sign in to Ravenna. Authenticate with your Ravenna account and approve the connection.

**5. Verify the connection**

Ravenna tools will be available through GitHub Copilot Chat in agent mode. Ask your assistant to list your Ravenna channels to confirm the connection works.

> [!TIP]
>
> Your OAuth token is scoped to your user account and grants access to all workspaces you have permissions for in the organization you signed in to. You can work across any of your workspaces in a single session.

Learn more about [MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)

***

### Other MCP clients

If your MCP client is not listed above, you can still connect it to Ravenna as long as it supports OAuth and remote HTTP servers. If you're using a client that does not yet support OAuth for remote MCP servers, reach out to us at [support@ravenna.ai](mailto:support@ravenna.ai) to discuss alternative authentication methods.

#### Custom MCP clients

Any MCP-compatible client that supports OAuth and remote HTTP servers can connect to Ravenna. Use these connection details:

* **URL:** `https://core.ravenna.ai/mcp`
* **Transport:** Streamable HTTP (may be labeled `http` or `streamable-http`)
* **Authentication:** OAuth 2.0 with automatic discovery
* **Callback URL:** Most clients handle this automatically. Common defaults:
  * VS Code: `http://127.0.0.1:33418/`
  * Claude Code: Configurable via `--callback-port`
  * Codex: `http://127.0.0.1:56567/callback/R1_hNylnFZtJ`, set with `mcp_oauth_callback_port = 56567` in `config.toml`
  * OpenCode: `http://127.0.0.1:56567/oauth/callback`, set with `oauth.redirectUri` in `opencode.json`
  * Cursor: `cursor://anysphere.cursor-mcp/oauth/callback`

Your client should automatically discover Ravenna's authorization server from the MCP endpoint and prompt you to sign in. Refer to your client's documentation for OAuth-based MCP server setup.

The `/mcp` endpoint uses Streamable HTTP and automatically discovers OAuth authorization server metadata. Ravenna's OAuth implementation supports the standard callback URLs used by popular MCP clients.

***

## Test your connection

**1. Check tool availability**

Ask your AI assistant: "What Ravenna tools do you have available?" It should list the available MCP tools.

**2. Run a simple query**

Try a basic read operation like "List my Ravenna channels" or "Get the current user."

**3. Verify results**

Confirm that the response contains actual data from your workspace, like real channel names or your user profile.

***

## Troubleshooting

> [accordion] Tools not appearing
>
> * Verify your configuration file is in the correct location for your client.
> * Check that the JSON is valid (no trailing commas, correct nesting).
> * Restart your AI client completely after making configuration changes.
> * Confirm the server URL is exactly `https://core.ravenna.ai/mcp`.

> [accordion] Authentication errors
>
> * Check that your API key is correct and has not been revoked.
> * Verify the `Authorization` header uses the `Bearer` prefix with a space before the token.
> * Ensure there are no extra spaces or newline characters in your key value.
> * If your key has **Allowed IP ranges** configured, confirm your client's public egress IP is inside one of those ranges. Requests from outside the allowlist return `403 Forbidden` and do not include a `WWW-Authenticate` header, and the error deliberately does not reveal that the key is IP-scoped. See [Restrict a key to specific IP ranges](https://docs.ravenna.ai/api/overview.md#restrict-a-key-to-specific-ip-ranges).

> [accordion] Callback URL mismatch
>
> Ravenna's sign-in page only accepts specific OAuth callback URLs. If your client sends any other URL, sign-in stops with `unauthorized_client: Callback URL mismatch`. The error shows the URL your client sent.
>
> For clients that use port `56567` (Codex, OpenCode, Claude Code, and Claude Desktop with `mcp-remote`), Ravenna accepts these callback URLs:
>
> * `http://127.0.0.1:56567/callback`
> * `http://localhost:56567/callback`
> * `http://127.0.0.1:56567/callback/R1_hNylnFZtJ` (Codex)
> * `http://localhost:56567/callback/R1_hNylnFZtJ` (Codex)
> * `http://127.0.0.1:56567/oauth/callback`
> * `http://localhost:56567/oauth/callback`
>
> To fix the error:
>
> * **Wrong port:** Set the callback port to `56567`. In Codex, add `mcp_oauth_callback_port = 56567` at the top of `config.toml`. In OpenCode, set `oauth.redirectUri` to `http://127.0.0.1:56567/oauth/callback`. In Claude Code, pass `--callback-port 56567`.
> * **Codex ignores the setting:** Confirm you edited the `config.toml` Codex actually reads (`~/.codex/config.toml`, or `$CODEX_HOME/config.toml`). Confirm `mcp_oauth_callback_port` sits above any `[table]` header. Update Codex to the latest version, then run `codex mcp login ravenna` again.
> * **Different ID after `/callback`:** Codex builds the ID from the server URL, so a different URL (for example, one with a trailing slash) produces a different ID. Set the server URL to exactly `https://core.ravenna.ai/mcp`, then run `codex mcp login ravenna` again.

> [accordion] No data returned
>
> * Confirm your API key is scoped to the workspace you expect.
> * Verify that your user account has the necessary permissions to access the requested data.
> * Try a simple operation like "get current user" to isolate whether the issue is with authentication or with a specific tool.

> [accordion] Forbidden or insufficient role errors
>
> The MCP server enforces your workspace and organization roles on every tool call.
>
> * Some tools require an Admin role in the target workspace. Member or Guest accounts cannot call them.
> * A few tools (such as creating users) require organization admin privileges.
> * Confirm your role in the target workspace from **Settings** → **Members** in the Admin, and ask a workspace admin to upgrade your role if needed.

> [accordion] Wrong workspace or workspace not found
>
> For tools that operate on a specific workspace, your assistant supplies a `workspaceId` on each call.
>
> * If your assistant targets the wrong workspace, name the workspace explicitly in your prompt (for example, *"In the IT Support workspace, ..."*).
> * If you connected with an API key, your session is pinned to the workspace that issued the key. Calls to any other workspace are rejected even if you are a member. Switch to OAuth to work across multiple workspaces.
> * A "workspace membership not found" error means your user account is not a member of the workspace you targeted. Add yourself to the workspace, or pick one you belong to.

> [accordion] Connection drops or timeouts
>
> * Some clients maintain a persistent connection to the server. If your network is interrupted, restart the client to reconnect.
> * If the connection drops after a period of inactivity, this is expected. Start a new conversation or restart the client.
> * Check that your network allows long-lived HTTPS connections and does not have aggressive idle timeouts.

Learn more about [available MCP tools](https://docs.ravenna.ai/documentation/automate/mcp/tools.md)


## Related topics

- [Setup](https://docs.ravenna.ai/integrations/okta/setup/overview.md)


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