Skip to main content
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.

​
Prerequisites

The MCP server authenticates with workspace API keys. 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

​
Configure your AI client

Select your AI client below and follow the steps to connect it to the Ravenna MCP server.

​
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

Claude Desktop’s MCP integration requires a transport type that is not yet supported by the Ravenna MCP server. Support for Claude Desktop is coming soon.

​
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

​
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 ()
  • Authorization header: Bearer YOUR_API_KEY
Different clients use different labels for HTTP transport. You may see it called http, streamable-http, or StreamableHTTP depending on the client. They all refer to the same protocol.

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

Specify the workspace when prompting

Your AI assistant will see both sets of tools. 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.”
{
  "mcpServers": {
    "ravenna-it": {
      "url": "https://core.ravenna.ai/mcp",
      "headers": {
        "Authorization": "Bearer wk_YOUR_IT_WORKSPACE_KEY"
      }
    },
    "ravenna-hr": {
      "url": "https://core.ravenna.ai/mcp",
      "headers": {
        "Authorization": "Bearer wk_YOUR_HR_WORKSPACE_KEY"
      }
    }
  }
}

​
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.
Learn more about available MCP tools