Setup - Ravenna Docs

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

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. 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 \
  http://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. 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.

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

Add the MCP server configuration

Add the following to your config.toml:

config.toml

# Set a fixed OAuth callback port (required by Ravenna)
mcp_oauth_callback_port = 56567

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

Authenticate with OAuth

Run the login command to initiate the OAuth flow:

Terminal

codex mcp login ravenna

Your browser will open 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’ll all use port 56567.

Learn more about MCP servers in Codex

Cursor

Cursor supports OAuth authentication for MCP servers. You can configure OAuth in two ways: dynamic OAuth (one-click from marketplace) or static OAuth (pre-configured credentials).

Option 1: Dynamic OAuth (Recommended)

If Ravenna is available in the Cursor Marketplace or cursor.directory, you can add it with one click and authenticate automatically.

Search for “Ravenna” in the Cursor Marketplace

Click “Add to Cursor” and follow the OAuth prompts in your browser

Verify the connection by asking Cursor to list your Ravenna channels

Option 2: Static OAuth Configuration

For manual OAuth setup, configure the server in .cursor/mcp.json with your OAuth credentials:

Contact your Ravenna workspace admin to register an OAuth client for Cursor. You’ll need:

Client ID
Client Secret (optional for public clients)
Redirect URI: cursor://anysphere.cursor-mcp/oauth/callback

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

Add the configuration below, replacing the client ID with your credentials:

.cursor/mcp.json

{
  "mcpServers": {
    "ravenna": {
      "url": "https://core.ravenna.ai/mcp",
      "auth": {
        "CLIENT_ID": "your-oauth-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "scopes": ["read", "write"]
      }
    }
  }
}

Restart Cursor

Restart Cursor to load the new MCP server configuration.

Complete OAuth flow

Cursor will prompt you to authenticate via OAuth. Follow the prompts in your browser to sign in to Ravenna.

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.

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.

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.

Learn more about MCP servers in VS Code

Other MCP Clients

Some MCP clients do not yet support OAuth authentication for remote HTTP servers. If you’re using one of these clients and would like OAuth support, please reach out to us at support@ravenna.ai to discuss alternative authentication methods.

Clients without OAuth support

Windsurf - OAuth support claimed but configuration details unavailable
Claude Desktop - Uses mcp-remote with API key headers, no OAuth support documented

We’re actively working with these platforms to enable OAuth authentication. Check back here for updates.

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: HTTP (may be labeled http, streamable-http, or sse)
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.

The /mcp endpoint supports both modern and legacy MCP transports 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.

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.

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

Documentation Index

​Sign in with OAuth

​Configure your AI client

​ChatGPT

​Claude Code

​Codex

​Cursor

​Option 1: Dynamic OAuth (Recommended)

​Option 2: Static OAuth Configuration

​VS Code

​Other MCP Clients

​Clients without OAuth support

​Custom MCP clients

​Test your connection

​Troubleshooting

Sign in with OAuth

Configure your AI client

ChatGPT

Claude Code

Codex

Cursor

Option 1: Dynamic OAuth (Recommended)

Option 2: Static OAuth Configuration

VS Code

Other MCP Clients

Clients without OAuth support

Custom MCP clients

Test your connection

Troubleshooting