Setup

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.

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:

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.

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.

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.

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.

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.

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

Fill in the details:

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

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

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

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.

Add the MCP server

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

claude mcp add ravenna \
  --transport http \
  https://core.ravenna.ai/mcp \
  --callback-port 56567

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.

Start a new session

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

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.

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

Codex

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

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.

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.

config.toml

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

Authenticate with OAuth

Run the login command to initiate the OAuth flow:

Terminal

codex mcp login ravenna

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

Verify the connection

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

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.

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 for fixes.

Learn more about MCP servers in Codex

OpenCode

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

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

Add the MCP server configuration

Add the following to your opencode.json:

opencode.json

{
  "$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.

Authenticate with OAuth

Run the auth command to initiate the OAuth flow:

Terminal

opencode mcp auth ravenna

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

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

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.

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

Add the Ravenna MCP server

Add the following configuration to your claude_desktop_config.json:

claude_desktop_config.json

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

Restart Claude Desktop

Restart Claude Desktop to load the new MCP server configuration.

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.

Verify the connection

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

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.

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.

Add the Ravenna MCP server

Add the following configuration:

.cursor/mcp.json

{
  "mcpServers": {
    "ravenna": {
      "url": "https://core.ravenna.ai/mcp"
    }
  }
}

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

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.

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.

Verify the connection

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

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

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.

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.

Add the Ravenna MCP server

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

.vscode/mcp.json

{
  "servers": {
    "ravenna": {
      "type": "http",
      "url": "https://core.ravenna.ai/mcp"
    }
  }
}

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

Reload VS Code

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

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.

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.

Learn more about MCP servers in VS Code

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

Check tool availability

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

Run a simple query

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

Verify results

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

Troubleshooting

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.

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.

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.

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.

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.

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.

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

Get started

Platform

Tickets

Automate

Measure

Configure your AI client

ChatGPT

Claude Code

Codex

OpenCode

Claude Desktop

Cursor

VS Code

Other MCP clients

Custom MCP clients

Test your connection

Troubleshooting

​Sign in with OAuth

​Configure your AI client

​ChatGPT

​Claude Code

​Codex

​OpenCode

​Claude Desktop

​Cursor

​VS Code

​Other MCP clients

​Custom MCP clients

​Test your connection

​Troubleshooting

Sign in with OAuth

Configure your AI client

ChatGPT

Claude Code

Codex

OpenCode

Claude Desktop

Cursor

VS Code

Other MCP clients

Custom MCP clients

Test your connection

Troubleshooting