> ## 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 an MCP client

> Connect Claude, Cursor, ChatGPT, or your editor to Ravenna through the MCP server so your AI assistant can read and act on tickets, users, and workflows.

Ravenna's MCP server puts your workspace inside whatever AI tool you already work in. Instead of switching to the Admin, you ask your assistant to triage tickets, look up users, or build a workflow, and it does it.

The real value shows up when you combine it with the other MCP servers your client is connected to: pull a start date from your HRIS and open an onboarding ticket with it in one message, without copying anything.

<Callout icon="flask-conical" color="#7C3AED">The MCP server is in beta. Send feedback to [support@ravenna.ai](mailto:support@ravenna.ai)</Callout>

<Steps>
  <Step title="Connect">
    Every client points at the same endpoint, `https://core.ravenna.ai/mcp`, and signs you in with OAuth using your existing Ravenna account. **Do not set an `Authorization` header.** Your client handles the token.

    <Tabs>
      <Tab title="Claude Code">
        One command, then a browser sign-in. The callback port matters.

        ```bash Terminal theme={"system"}
        claude mcp add ravenna \
          --transport http \
          https://core.ravenna.ai/mcp \
          --callback-port 56567
        ```

        Approve the connection in the browser, then start a new session. Run `/mcp` to check server status.
      </Tab>

      <Tab title="Cursor">
        Add the server to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for every project:

        ```json .cursor/mcp.json theme={"system"}
        {
          "mcpServers": {
            "ravenna": {
              "url": "https://core.ravenna.ai/mcp"
            }
          }
        }
        ```

        Then open **Cursor Settings** > **Tools & MCP** and toggle Ravenna on. Cursor opens the sign-in flow the first time you use it.
      </Tab>

      <Tab title="ChatGPT">
        Add the MCP server URL in ChatGPT's connector settings and sign in to Ravenna in the browser pop-up. No configuration file, no API key.
      </Tab>

      <Tab title="Others">
        Codex, Claude Desktop, and VS Code all work, along with any MCP client that supports OAuth. The setup reference has the exact config file path and format for each.

        <Callout icon="link" color="#6B7280">Learn more in the [MCP setup reference](/documentation/automate/mcp/setup#configure-your-ai-client)</Callout>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Verify it worked">
    Ask your assistant:

    <Prompt description="What Ravenna tools do you have available?">
      What Ravenna tools do you have available?
    </Prompt>

    <Prompt description="List my Ravenna channels">
      List my Ravenna channels
    </Prompt>

    If you get real channel names back, you are connected. If the tools do not appear at all, restart the client completely, check the JSON for trailing commas, and confirm the URL is exactly `https://core.ravenna.ai/mcp`.
  </Step>

  <Step title="Name the workspace">
    Your account can span several workspaces, so every workspace-scoped call needs to know which one. Say it in the prompt and your assistant resolves it:

    <Prompt description="In the IT Support workspace, list open tickets assigned to me">
      In the IT Support workspace, list open tickets assigned to me
    </Prompt>

    Two rules worth knowing before you debug something that is not broken:

    * **OAuth reaches every workspace you belong to.** This is why OAuth is the right choice for almost everyone.
    * **API key connections are pinned to the workspace that issued the key.** Calls to any other workspace are rejected even if you are a member. If you need to work across workspaces in one session, use OAuth.

    A "workspace membership not found" error means your account is not a member of the workspace you named, not that the workspace is missing.
  </Step>

  <Step title="Understand what it can and cannot do">
    The server enforces your existing Ravenna roles on every call. Your assistant can do exactly what you can do in the Admin, nothing more:

    * Most workspace tools allow Admin and Member roles
    * Some configuration tools are Admin only
    * A few, like creating users, need organization admin
    * Guests cannot call workspace tools at all

    A forbidden error is a role problem. Check your role at **Settings** > **Members**.

    <Callout icon="link" color="#6B7280">Learn more about [permissions and workspace targeting](/documentation/automate/mcp/overview#permissions-and-workspace-targeting)</Callout>
  </Step>
</Steps>

## What to actually use it for

Copilot is better inside the Admin, because it already has page context. MCP wins when Ravenna is one of several systems in the same task.

**Cross-system ticket creation**

<Prompt description="Look up Jamie Lee in HiBob, then create an onboarding ticket in the IT Support channel with their department, start date, and manager">
  Look up Jamie Lee in HiBob, then create an onboarding ticket in the IT Support channel with their department, start date, and manager
</Prompt>

**Incident follow-up in bulk**

<Prompt description="Pull the resolution notes from the DNS outage post-mortem in Incident.io, post a summary on all open tickets tagged dns-outage, and move them to Resolved">
  Pull the resolution notes from the DNS outage post-mortem in Incident.io, post a summary on all open tickets tagged dns-outage, and move them to Resolved
</Prompt>

**Planning your own day**

<Prompt description="What tickets are assigned to me across all my workspaces? Prioritize by due date and flag anything overdue.">
  What tickets are assigned to me across all my workspaces? Prioritize by due date and flag anything overdue.
</Prompt>

**Reviewing a channel for stale work**

<Prompt description="Show me open tickets in the IT Support channel waiting more than 48 hours. Which are unassigned?">
  Show me open tickets in the IT Support channel waiting more than 48 hours. Which are unassigned?
</Prompt>

<Callout icon="link" color="#6B7280">Learn more about the [full tool catalog](/documentation/automate/mcp/tools) and [troubleshooting](/documentation/automate/mcp/setup#troubleshooting)</Callout>

## Next

<CardGroup cols={2}>
  <Card title="Copilot recipes" icon="sparkles" href="/guides/how-to/copilot-recipes" horizontal>
    The same jobs, done inside the Admin with page context.
  </Card>

  <Card title="Foundry" icon="wrench" href="/guides/how-to/foundry/overview" horizontal>
    Give your agents custom tools against your own APIs.
  </Card>
</CardGroup>


## Related topics

- [Copilot recipes](/guides/how-to/copilot-recipes.md)
- [Guides](/guides/overview.md)
- [Setup](/documentation/automate/mcp/setup.md)
- [Connect a client_credentials OAuth provider and create an integration](/api/foundry-oauth-providers/connect-a-client_credentials-oauth-provider-and-create-an-integration.md)
- [MCP server](/documentation/automate/mcp/overview.md)