Setup - Ravenna Docs | Agentic Service Management for Every Team

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

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

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.

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.

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

​Sign in with OAuth

​Configure your AI client

​ChatGPT

​Claude Code

​Codex

​Claude Desktop

​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

Claude Desktop

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