> ## 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:**

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  OAuth tokens are scoped to your user account and grant access to all workspaces and data that your account has permissions to access. Your assistant can work across any of your workspaces in a single session.
</Tip>

***

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

<Steps>
  <Step>
    In ChatGPT, open **Settings** → **Connectors** → **Add custom connector**.
  </Step>

  <Step>
    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>

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

  <Step>
    Start a new ChatGPT conversation and ask it to list your Ravenna tools to confirm the connection.
  </Step>
</Steps>

<Tip>
  Your ChatGPT connection is scoped to your user account and grants access to all workspaces you have permissions for. Specify which workspace you want to work with when prompting your assistant.
</Tip>

***

### Claude Code

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

<Steps>
  <Step title="Add the MCP server">
    Run the command below in your terminal. The `--callback-port 56567` option is critical for the OAuth callback.

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

  <Step title="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.
  </Step>

  <Step title="Start a new session">
    Open a new Claude Code session. The Ravenna tools will be available automatically.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  Your OAuth token is scoped to your user account and grants access to all workspaces you have permissions for. You can work across any of your workspaces in a single session.
</Tip>

<Callout icon="link" color="#6B7280">
  Learn more about [MCP servers in Claude Code](https://code.claude.com/docs/en/mcp)
</Callout>

***

### Codex

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

<Steps>
  <Step title="Locate or create your config file">
    Codex stores MCP configuration in `config.toml`. The exact location depends on your platform:

    * **macOS:** `~/Library/Application Support/Codex/config.toml`
    * **Linux:** `~/.config/codex/config.toml`
    * **Windows:** `%APPDATA%\Codex\config.toml`
  </Step>

  <Step title="Add the MCP server configuration">
    Add the following to your `config.toml`:

    ```toml config.toml theme={"system"}
    # Set a fixed OAuth callback port (required by Ravenna)
    mcp_oauth_callback_port = 56567

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

  <Step title="Authenticate with OAuth">
    Run the login command to initiate the OAuth flow:

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

    Your browser will open automatically. Sign in to Ravenna and approve the connection.
  </Step>

  <Step title="Verify the connection">
    Start Codex and ask it to list your Ravenna channels to confirm the connection works.
  </Step>
</Steps>

<Tip>
  The OAuth callback port setting is shared across all MCP servers in Codex. If you connect to multiple OAuth-based MCP servers, they'll all use port 56567.
</Tip>

<Callout icon="link" color="#6B7280">
  Learn more about [MCP servers in Codex](https://developers.openai.com/codex/mcp)
</Callout>

***

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

<Steps>
  <Step title="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`
  </Step>

  <Step title="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"
          ]
        }
      }
    }
    ```
  </Step>

  <Step title="Restart Claude Desktop">
    Restart Claude Desktop to load the new MCP server configuration.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Verify the connection">
    Ask Claude to list your Ravenna tools to confirm the connection works.
  </Step>
</Steps>

<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.
</Tip>

***

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Verify the connection">
    Ask Cursor to list your Ravenna channels to confirm the connection works.
  </Step>
</Steps>

<Tip>
  Your OAuth token is scoped to your user account and grants access to all workspaces you have permissions for.
</Tip>

<Callout icon="link" color="#6B7280">
  Learn more about [MCP servers in Cursor](https://cursor.com/docs/mcp)
</Callout>

***

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Reload VS Code">
    Reload the window or restart VS Code to load the new MCP server configuration.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  Your OAuth token is scoped to your user account and grants access to all workspaces you have permissions for. You can work across any of your workspaces in a single session.
</Tip>

<Callout icon="link" color="#6B7280">
  Learn more about [MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
</Callout>

***

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

<Callout type="info">
  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.
</Callout>

***

## Test your connection

<Steps>
  <Step title="Check tool availability">
    Ask your AI assistant: "What Ravenna tools do you have available?" It should list the available MCP tools.
  </Step>

  <Step title="Run a simple query">
    Try a basic read operation like "List my Ravenna channels" or "Get the current user."
  </Step>

  <Step title="Verify results">
    Confirm that the response contains actual data from your workspace, like real channel names or your user profile.
  </Step>
</Steps>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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>

  <Accordion title="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 Ravenna web app, and ask a workspace admin to upgrade your role if needed.
  </Accordion>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

<Callout icon="link" color="#6B7280">
  Learn more about [available MCP tools](/documentation/automate/mcp/tools)
</Callout>