> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rogeriq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

Run rogeriq as a Model Context Protocol server so Claude / Cursor / Windsurf can call the API as native tools.

# MCP server

The CLI ships an embedded MCP (Model Context Protocol) server over stdio.
Once configured, Claude Desktop / Claude Code / Cursor / any
MCP-compatible client gets typed tools for managing conversations,
projects, knowledge base, widget, integrations, and webhooks — no shell
syntax required.

## Configure Claude Desktop

Edit your Claude Desktop config (`~/Library/Application
Support/Claude/claude_desktop_config.json` on macOS,
`%APPDATA%/Claude/claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "rogeriq": {
      "command": "rogeriq",
      "args": ["mcp"],
      "env": {
        "RIQ_API_KEY": "riq_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "RIQ_PROJECT_ID": "prj_xxxxxxxxxxxxx",
        "RIQ_ORG_ID": "org_xxxxxxxxxxxxx"
      }
    }
  }
}
```

Restart Claude Desktop. You'll see "rogeriq" appear in the tools panel.

## Configure Claude Code

```bash
claude mcp add rogeriq -- rogeriq mcp
```

Then set the env vars in your shell or pass them through:

```bash
RIQ_API_KEY=riq_xxx RIQ_PROJECT_ID=prj_xxx claude mcp add rogeriq -- rogeriq mcp
```

## Configure Cursor / Windsurf

Both accept the same JSON shape as Claude Desktop. Add the entry to
their MCP config and restart.

## What tools are exposed

Run this to see the full schema (useful for sharing with LLMs that don't
auto-discover):

```bash
rogeriq mcp list-tools
```

Tools as of CLI 0.3.0:

| Tool | What it does |
|------|--------------|
| `list_conversations` | Filter open tickets by status, priority, channel, contact, query |
| `get_conversation` | Fetch one ticket + recent messages |
| `reply_to_conversation` | Send a reply or internal note |
| `update_conversation` | Change status, priority, assignee, tags |
| `list_contacts` | Browse customers |
| `upsert_contact` | Create or update a contact by email / external_id |
| `search_knowledge_base` | Find articles by query |
| `list_kb_articles` | Browse KB |
| `create_kb_article` | Add a new article |
| `agent_respond` | Have the AI agent draft + send a response |
| `list_projects` | List projects in the current org |
| `create_project` | Create a new project |
| `get_widget_config` | Read widget settings |
| `update_widget_config` | Theme, launcher, colors, welcome message |
| `list_integrations` | Connected third-party integrations |
| `browse_integration_catalog` | All available integrations + install state |
| `get_integration_install_url` | Get the browser URL to install a provider |
| `disconnect_integration` | Disconnect an integration |
| `list_webhooks` | List webhook subscriptions |
| `create_webhook` | Subscribe to events |

## How it works

The MCP server reads tool calls over stdin as JSON-RPC 2.0, dispatches
through the same `ApiClient` the rest of the CLI uses, and writes
responses to stdout. Errors are returned as MCP tool errors (so the LLM
can recover) rather than thrown.

The same auth and scope rules apply: tier-aware rate limiting, granular
scopes enforced server-side, audit log tracks the key.

## Multi-project setups

For agents that span multiple projects, register multiple MCP servers
with different `RIQ_PROJECT_ID` values:

```json
{
  "mcpServers": {
    "rogeriq-prod": {
      "command": "rogeriq",
      "args": ["mcp"],
      "env": { "RIQ_API_KEY": "riq_prod_xxx", "RIQ_PROJECT_ID": "prj_prod" }
    },
    "rogeriq-staging": {
      "command": "rogeriq",
      "args": ["mcp"],
      "env": { "RIQ_API_KEY": "riq_staging_xxx", "RIQ_PROJECT_ID": "prj_staging" }
    }
  }
}
```

The LLM picks the right tool prefix based on the question.