MCP server

Connect Claude Code, Codex, Cursor or VS Code to Rolebase with the MCP server, and how it works.

Overview

Rolebase exposes a Model Context Protocol (MCP) server, so AI assistants can read and update organizations with the permissions of the user who owns the API key. For ChatGPT, Claude and Mistral Vibe, see the MCP connector page of the documentation.

Endpoint

Environment	URL
Production	`https://api.rolebase.io/mcp`
Local development	`http://localhost:8888/mcp`

The server uses the Streamable HTTP transport and keeps no session between requests. It authenticates with an API key, sent in the x-api-key header, as Authorization: Bearer <your-api-key>, or, only for clients that accept no header, such as ChatGPT, in the URL (/mcp/<your-api-key>). A missing or invalid key gets a 400 response, so clients show the error instead of starting an OAuth flow.

Key in the URL

Use the URL form only when the client offers no other way: the client may display or store the URL, and anyone who sees it gets the key. The server logs hide it.

Developer tools

Create an API key from My account > API keys, then add the server to your tool.

Claude Code

claude mcp add --transport http rolebase https://api.rolebase.io/mcp \
  --header "x-api-key: <your-api-key>"

Codex

Add the server to ~/.codex/config.toml. The Codex CLI, the IDE extension and the desktop app share this file. The key is read from the ROLEBASE_API_KEY environment variable:

[mcp_servers.rolebase]
url = "https://api.rolebase.io/mcp"
env_http_headers = { "x-api-key" = "ROLEBASE_API_KEY" }

Cursor

Add the server to ~/.cursor/mcp.json for all your projects, or to .cursor/mcp.json in a project:

{
  "mcpServers": {
    "rolebase": {
      "url": "https://api.rolebase.io/mcp",
      "headers": { "x-api-key": "<your-api-key>" }
    }
  }
}

VS Code

In the Command Palette, run MCP: Open User Configuration to edit the mcp.json of your user profile, available in every workspace. For a single project, create .vscode/mcp.json instead. With this configuration, VS Code asks for the key when the server first starts and stores it securely, so the file holds no secret:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "rolebase-api-key",
      "description": "Rolebase API key",
      "password": true
    }
  ],
  "servers": {
    "rolebase": {
      "type": "http",
      "url": "https://api.rolebase.io/mcp",
      "headers": { "x-api-key": "${input:rolebase-api-key}" }
    }
  }
}

Tools

Tool	What it does
`graphql`	Runs a query or a mutation on the GraphQL API.
`graphql_schema`	Lists the root fields of the GraphQL schema, or prints a type with its fields.
`trpc_procedures`	Lists the tRPC procedures the assistant can call, with their input.
`trpc`	Calls a tRPC procedure, such as inviting a member or archiving a role with its sub-roles.

These tools expose the GraphQL schema and the tRPC router as they are, so the assistant always works with the current API. Internal procedures stay out of reach. On connection, the server also sends the assistant the guide shared with the Rolebase skill.

Alternative: the Rolebase skill

For agents that work in a terminal, the Rolebase skill is an alternative to the MCP server: it calls the HTTP API with an API key read from the environment, and follows the same guide. To connect a chat assistant such as Claude, ChatGPT or Mistral Vibe, see the Use Rolebase with an AI assistant guide.