Skip to main content

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.

Connect your AI assistant to Ravenna by generating an and adding the MCP server to your client’s configuration. All requests go through a single endpoint: https://core.ravenna.ai/mcp.
Only workspace admins can create these keys. If you are not an admin, ask your workspace admin to generate one for you. Learn how to create and manage API keys.

​
Multi-workspace access

API keys are scoped to a single workspace, and each MCP server entry only accepts one key. If you work across multiple workspaces, you need a separate MCP server entry for each one, with a unique name to tell them apart.
1

Create an API key in each workspace

Switch to each workspace in the Ravenna web app and create a dedicated API key. Give each key a name that identifies the workspace (for example, “MCP - IT Support”, “MCP - HR”).
2

Add a named entry for each workspace

In your client’s configuration, add one MCP server entry per workspace.
Use a descriptive name like ravenna-it or ravenna-hr so your AI assistant can distinguish between them. Including the workspace name makes it easy to remember which is which.
3

Specify the workspace when prompting

Your AI assistant will see all sets of tools for each Ravenna workspace you connect. When making a request, mention which workspace you mean so the assistant uses the correct connection. For example, “List open tickets in the IT Support workspace” or “Use ravenna-it to list my open tickets”.Make sure you review the tool call carefully before confirming, to ensure it is using the correct workspace connection.

​
Configure your AI client

​
ChatGPT

ChatGPT’s MCP integration requires OAuth authentication, which is not yet supported by the Ravenna MCP server. Support for ChatGPT is coming soon.

​
Claude Desktop

Each Ravenna workspace has its own API key. Repeat the server block for as many workspaces as you need, just give each a unique name and its own environment variable.
1
Locate your Claude Desktop config file:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
2
Add an entry to mcpServers for each Ravenna workspace you want to access. Name each one ravenna-{{ workspace }} and use its corresponding API key:
    {
      "mcpServers": {
        "ravenna-engineering": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://core.ravenna.ai/mcp",
            "--header",
            "Authorization: Bearer ${RAVENNA_ENGINEERING_API_KEY}"
          ],
          "env": {
            "RAVENNA_ENGINEERING_API_KEY": "your-engineering-workspace-api-key"
          }
        },
        "ravenna-marketing": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://core.ravenna.ai/mcp",
            "--header",
            "Authorization: Bearer ${RAVENNA_MARKETING_API_KEY}"
          ],
          "env": {
            "RAVENNA_MARKETING_API_KEY": "your-marketing-workspace-api-key"
          }
        }
      }
    }
3
Replace each your-...-api-key with the API key for that workspace, found in your Ravenna dashboard under Settings → API Keys.
4
Save the file and fully quit and relaunch Claude Desktop. Each workspace will appear as a separate MCP server under Settings → Developer.
Node.js must be installed on your machine for npx mcp-remote to work. You can download it from npmjs.com/package/mcp-remote.

​
Claude Code

Claude Code manages MCP servers through the CLI. A single terminal command registers the Ravenna server with your API key. No config files to edit.
1

Add the MCP server

Run the command below in your terminal, replacing YOUR_API_KEY with your actual key.
2

Start a new session

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

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.
claude mcp add ravenna \
  --transport http \
  https://core.ravenna.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
Learn more about MCP servers in Claude Code

​
Codex

Each Ravenna workspace has its own API key. Add a new MCP integration for as many workspaces as you need, just give each a unique name.
Learn more about MCP servers in Codex
1
Open Codex and go to Settings → MCP Servers → Add MCP Server.
2
Codex MCP server configuration dialog showing name, transport, URL, and header fieldsFill in the details:
  1. Name: ravenna-{{ workspace }}
  2. Select Streamable HTTP
  3. URL: https://core.ravenna.ai/mcp
  4. Headers key: Authorization
  5. Headers value: your workspace API key
3
Click Save. Repeat for each additional Ravenna workspace.

​
Cursor

Cursor uses a JSON configuration file for MCP servers. You add the Ravenna server to .cursor/mcp.json, then connect it through Cursor’s settings UI.
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

Paste the configuration below, replacing YOUR_API_KEY with your actual key.
3

Connect in Cursor settings

Go to Cursor Settings > Tools & MCP. You should see Ravenna listed. Click Connect if it is not already connected.
4

Verify the connection

Restart Cursor or reload the window. Ask Cursor to list your Ravenna channels to confirm tools are available.
{
  "mcpServers": {
    "ravenna": {
      "url": "https://core.ravenna.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
Learn more about MCP servers in Cursor

​
VS Code

VS Code supports MCP servers natively through configuration files. You add the Ravenna server configuration to an mcp.json file, and the tools become available through Copilot Chat in agent mode.
1

Create the configuration file

Create a file called .vscode/mcp.json in your project root. For global access across all projects, press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux), select Preferences: Open User Settings (JSON), and add the mcp block shown below.
2

Add the Ravenna MCP server

Add the configuration below, replacing YOUR_API_KEY with your actual key.
3

Reload VS Code

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

Verify the connection

Ravenna tools will be available through Copilot Chat in agent mode. Ask your assistant to list your Ravenna channels to confirm.
{
  "servers": {
    "ravenna": {
      "type": "http",
      "url": "https://core.ravenna.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
Learn more about MCP servers in VS Code

​
Windsurf

Windsurf uses a JSON configuration file for MCP servers. You add the Ravenna server to the Windsurf config file, then restart the app.
1

Open the configuration file

Create or edit ~/.codeium/windsurf/mcp_config.json.
2

Add the Ravenna MCP server

Paste the configuration below, replacing YOUR_API_KEY with your actual key.
3

Restart Windsurf

Restart Windsurf to load the new MCP server configuration.
4

Verify the connection

Ask Windsurf to list your Ravenna channels to confirm tools are available.
{
  "mcpServers": {
    "ravenna": {
      "serverUrl": "https://core.ravenna.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
Learn more about MCP servers in Windsurf

​
Other clients

Any MCP-compatible client that supports remote HTTP servers can connect to Ravenna. Use the following connection details and refer to your client’s documentation for where to add remote MCP server configurations.
  • URL: https://core.ravenna.ai/mcp
  • Transport: HTTP (labeled http, streamable-http, or sse depending on your client)
  • Authorization header: Bearer YOUR_API_KEY
The /mcp endpoint supports both modern and legacy MCP transports. Your client connects to the same URL regardless of which transport it uses, and the server detects the protocol automatically.

​
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

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