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

# Response MCP Servers

> The remote agent-building MCP server at POST /api/mcp, and the local stdio analytics/reporting server.

# Response MCP Servers

ResponseCX ships two Model Context Protocol servers with different jobs.

| Server                 | Transport                          | For                                                         |
| ---------------------- | ---------------------------------- | ----------------------------------------------------------- |
| **ResponseCX remote**  | Streamable HTTP at `POST /api/mcp` | An external agent **building and tuning** ResponseCX agents |
| **Response analytics** | Local stdio                        | Claude Desktop reading **analytics and reporting** data     |

***

## Remote agent-building server

An external AI agent connects with its `rcx_` API key as a Bearer token and gets a
**scope-filtered toolset** for building ResponseCX agents.

```
POST /api/mcp
Authorization: Bearer rcx_...
```

The key is authenticated by the same guard as the [REST v1 API](/stateset-response/response-public-api).
Scopes gate each individual tool, and `tools/list` advertises **only** the tools the key's
scopes permit — an unauthorized tool is never even visible.

<Note>
  The server is **stateless**: each JSON-RPC POST builds a fresh server and transport, so there
  is no cross-request session state to leak between tenants. Tool output is capped at 60,000
  characters and truncated with a marker beyond that.
</Note>

### Tools

**Discovery** — so an agent can orient before it writes anything:

| Tool                  | Purpose                                                                   |
| --------------------- | ------------------------------------------------------------------------- |
| `describe_workspace`  | What exists in this workspace                                             |
| `describe_vocabulary` | The legal terms for rule conditions — stops the model guessing at grammar |

**Building:**

| Tool                                                          | Purpose                                                                             |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `provision_agent`                                             | Build a complete agent — settings, rules, functions, knowledge — in one atomic call |
| `build_support_agent`                                         | Opinionated support-agent scaffold                                                  |
| `create_agent` / `update_agent` / `get_agent` / `list_agents` | Agent lifecycle                                                                     |
| `configure_agent` / `get_agent_settings`                      | Model and behavior settings                                                         |
| `add_rule` / `update_rule` / `list_rules`                     | Rules                                                                               |
| `add_function` / `update_function` / `list_functions`         | Functions                                                                           |
| `add_knowledge` / `search_knowledge`                          | Knowledge base                                                                      |

**Verifying:**

| Tool          | Purpose                                             |
| ------------- | --------------------------------------------------- |
| `test_agent`  | Exercise the agent — closes the build → verify loop |
| `audit_agent` | Review an agent's configuration                     |

**Reading:**

| Tool                              | Purpose             |
| --------------------------------- | ------------------- |
| `list_responses` / `get_response` | Response history    |
| `analytics_summary`               | Aggregate analytics |

### Resources

Re-readable context a client can attach without spending a tool call — notably `vocabulary`
and `workspace`.

### The build → verify loop

The intended flow for an agent building an agent:

1. `describe_workspace` and `describe_vocabulary` to orient.
2. `provision_agent` to create the whole thing atomically.
3. `test_agent` to exercise it.
4. `audit_agent`, then `update_rule` / `update_function` to correct.

Errors come back as safe, model-readable messages — internals are never leaked.

***

## Local analytics server

A stdio MCP server that lets Claude Desktop call the Response analytics and reporting API
through a small authenticated bridge.

### Run it

```bash theme={null}
RESPONSE_API_BASE_URL=http://localhost:3000 \
RESPONSE_API_TOKEN=<cli-token> \
RESPONSE_ORG_ID=<org-id> \
npm run mcp:response-api
```

Optional:

* `RESPONSE_INTERNAL_SECRET` (or `INTERNAL_API_SECRET`) adds `x-internal-secret` for
  internal-only routes.
* `RESPONSE_MCP_MAX_RESPONSE_CHARS` caps large tool responses. Default `60000`.

### Claude Desktop

```json theme={null}
{
  "mcpServers": {
    "response-analytics": {
      "command": "node",
      "args": ["/path/to/scripts/response-api-mcp-server.mjs"],
      "env": {
        "RESPONSE_API_BASE_URL": "https://your-response-host",
        "RESPONSE_API_TOKEN": "<cli-token>",
        "RESPONSE_ORG_ID": "<org-id>"
      }
    }
  }
}
```

### Tools

| Tool                                 | Returns                                                                                                                                                                                            |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `response_analytics_overview`        | The comprehensive reporting payload: response volume, ratings, channels, AI resolution rate, widget activity, commerce signals, question themes, support performance, funnel steps, response times |
| `response_widget_analytics`          | The widget/chat subset: conversations, messages, widget events, funnel, handoff/containment, response time, commerce activity                                                                      |
| `response_dashboard_stats`           | Compact dashboard stats                                                                                                                                                                            |
| `response_responses_created`         | Recently created responses, filterable by date range, channel, rating, function-call status, and search                                                                                            |
| `response_response_analytics_export` | Response rows for analytics and export                                                                                                                                                             |
| `response_response_count`            | Total response count for the authenticated organization                                                                                                                                            |
| `response_chat_conversations`        | Chat/widget conversations with manager reporting fields — latest customer/agent messages, escalation and review state, status, counts, linked response signals                                     |
| `response_chat_thread`               | One conversation transcript with recent messages, counts, attachments, and response history                                                                                                        |
| `response_cx_reporting_bundle`       | The core CX reporting dataset in one call                                                                                                                                                          |
| `response_api_health`                | Checks `/api/health`                                                                                                                                                                               |
| `response_reporting_api_request`     | Operator/debug escape hatch for allowlisted `/api/...` routes                                                                                                                                      |
| `response_mcp_servers`               | Available MCP integrations for the organization                                                                                                                                                    |

### CX reporting flow

For a broad report, start with `response_cx_reporting_bundle`. For deeper evidence, use
`response_responses_created` to pull filtered response rows and `response_chat_conversations`
to find relevant threads. Use `response_chat_thread` when you need the actual transcript.

<Note>
  The analytics server only accepts `/api/...` paths and never writes logs to stdout, so the MCP
  JSON-RPC channel stays clean.
</Note>

## Related

* [Response Public API (v1)](/stateset-response/response-public-api)
* [MCP Integration Guide](/guides/mcp-integration-guide)