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

​
ChatGPT

ChatGPT supports MCP servers through its Apps feature. You create a custom app in ChatGPT’s settings, point it to the Ravenna endpoint, and configure API key authentication. Your ChatGPT team admin may need to enable Custom Apps first.
1

Open app settings

In ChatGPT, go to Settings > Apps. If you do not see an Advanced Settings option in the Apps menu, ask your ChatGPT team administrator to enable Custom Apps for your account.
2

Create a new app

Click Create app. Name it “Ravenna” and enter the server URL: https://core.ravenna.ai/mcp.
3

Configure authentication

Set the authentication type to API Key. Enter your Ravenna API key and set the header name to Authorization with the value Bearer YOUR_API_KEY.
4

Save and verify

Click Create to save the app. Start a new conversation and ask ChatGPT to list your Ravenna channels to confirm the connection works.

​
Claude Desktop

Claude Desktop uses a JSON configuration file to manage MCP servers. You add the Ravenna server entry to this file with your API key, then restart the app.
1

Open the configuration file

Locate or create the Claude Desktop configuration file:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
Create the file if it does not exist.
2

Add the Ravenna MCP server

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

Restart Claude Desktop

Quit and reopen Claude Desktop. You should see Ravenna listed in the tools menu.
4

Verify the connection

Start a new conversation and ask Claude to list your Ravenna channels to confirm tools are available.
{
  "mcpServers": {
    "ravenna": {
      "type": "streamable-http",
      "url": "https://core.ravenna.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

​
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.
claude mcp add ravenna \
  --transport streamable-http \
  https://core.ravenna.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

​
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 or home directory.
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": {
      "type": "streamable-http",
      "url": "https://core.ravenna.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

​
VS Code

VS Code supports MCP servers natively through its user settings. You add the Ravenna server configuration to settings.json, and the tools become available through Copilot Chat or any MCP-compatible extension.
1

Open user settings

Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux), then select Preferences: Open User Settings (JSON).
2

Add the Ravenna MCP server

Add the configuration below to your settings.json, 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 or any MCP-compatible extension. Ask your assistant to list your Ravenna channels to confirm.
{
  "mcp": {
    "servers": {
      "ravenna": {
        "type": "streamable-http",
        "url": "https://core.ravenna.ai/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY"
        }
      }
    }
  }
}

​
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": {
      "type": "streamable-http",
      "url": "https://core.ravenna.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

​
Other clients

Any MCP-compatible client that supports the transport 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: streamable-http
  • Authorization header: Bearer YOUR_API_KEY

​
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": {
      "type": "streamable-http",
      "url": "https://core.ravenna.ai/mcp",
      "headers": {
        "Authorization": "Bearer wk_YOUR_IT_WORKSPACE_KEY"
      }
    },
    "ravenna-hr": {
      "type": "streamable-http",
      "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