# Qualia MCP

**MCP server for the Qualia title and escrow platform** -- talk to your orders,
messages, and documents from Claude, Cursor, or any MCP client. First MCP in
the title & escrow vertical.

## What you can do with it

```
You:   "List orders awaiting closing and group by status."
Claude: *calls list_orders, summarises by status*

You:   "Send the buyer an update on the closing timeline for ORD-12345."
Claude: *calls send_message with subject + body, confirms the result*

You:   "What documents are attached to order ORD-98765?"
Claude: *calls list_documents, returns the file list*
```

## Why this exists

Qualia is the leading digital closing platform for the title & escrow
industry. Their public [Qualia API](https://www.qualia.com/qualia-api/)
exposes a read-write GraphQL surface for placing orders, exchanging
messages and documents, and pulling analytics -- but there was no MCP
wrapper until now. Title & escrow shops run on tight margins and the manual
data-entry tax is high; this MCP lets an AI agent drive Qualia the same
way a human would.

Other title & escrow platforms (SoftPro, RamQuest, Resware) have no MCP
either. This one targets Qualia specifically because it has the largest
market share, a public GraphQL API, and a vendor partner program
(`partners@qualia.com`).

## Install

```bash
pip install -e .
```

## Configure

```bash
export QUALIA_USERNAME="your-org-id"
export QUALIA_API_KEY="your-secret-key"
```

Capability gates must be enabled on your organization for the tools you
need. Contact `partners@qualia.com` to request access. Write tools
(`send_message`) will fail with `CAPABILITY_GATE_MISSING` until the gate
is enabled.

## Use with Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "qualia": {
      "command": "qualia_mcp",
      "env": {
        "QUALIA_USERNAME": "your-org-id",
        "QUALIA_API_KEY": "your-secret-key"
      }
    }
  }
}
```

## Use with Claude Code

```bash
claude mcp add qualia -- qualia_mcp \
  --env QUALIA_USERNAME=your-org-id --env QUALIA_API_KEY=your-secret-key
```

## Tools

| Tool | Type | Capability gate | What it does |
| --- | --- | --- | --- |
| `health_check` | Diagnostic | none | Verifies credentials + GraphQL connectivity |
| `get_organization` | Read | `organization:read` | Returns the authenticated org (id, name, displayName) |
| `list_orders` | Read | `orders:read` | Paginated title orders with optional status filter |
| `get_order` | Read | `orders:read` | Single order detail (status, property address, timestamps) |
| `list_messages` | Read | `messages:read` | Messages on a title order (subject, body, author) |
| `send_message` | Write | `messages:write` | Post a new message on a title order |
| `list_documents` | Read | `documents:read` | Documents attached to a title order |

## Engineering notes

- **GraphQL + typed errors.** Qualia returns 200 OK with an `errors[]` array
  on GraphQL validation failures. We promote those to typed exceptions
  (`QualiaAuthError` for `CAPABILITY_GATE_MISSING` / `UNAUTHENTICATED`,
  `QualiaNotFoundError` for `NOT_FOUND`, `QualiaRateLimitError` for
  `RATE_LIMITED`, generic `QualiaGraphQLError` otherwise) so agents can
  branch on cause instead of message text.
- **isError-compliance.** Every tool raises on failure (instead of
  returning the error as a string). FastMCP's wire-level `isError=true`
  flag is only set when a tool raises, so the agent can distinguish
  failure from success.
- **JSONL audit logging.** Every tool call writes a structured record to
  stderr (or a file path via `QUALIA_AUDIT_LOG`) for SOC2 auditability.
  Secret fields (`api_key`, `password`, `token`, etc.) are auto-redacted.
- **Retry with backoff.** Transient 5xx and 429 responses retry up to 3
  times with exponential backoff + full jitter, honoring `Retry-After`.

## Development

```bash
pip install -e ".[dev]"
ruff check src tests
ruff format --check src tests
mypy src
pytest
```

## License

MIT.

## See also

- [Qualia API docs](https://www.qualia.com/qualia-api/)
- [Model Context Protocol spec](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)
- [Other vertical MCPs in this portfolio](https://github.com/sanjibani?q=-mcp)
- [Custom MCP engagements](https://sanjibani.github.io/mcp-services/)