Claude

claude mcp add --transport http understanding https://api.theunderstanding.company/mcp/claude \
  --header "Authorization: Bearer $UNDERSTANDING_API_KEY"

{
  "mcpServers": {
    "understanding": {
      "command": "node",
      "args": ["/absolute/path/to/understanding-mcp/index.js"],
      "env": { "UNDERSTANDING_API_KEY": "usk_live_..." }
    }
  }
}

My statement has a charge from DRAFTKINGS with merchant category code 7995. Is that a restricted merchant?

{"abstain":false,"answer":true,"probability":0.97,"reasons":["mcc_7995","rule_gambling_category","kind_sportsbook"],"decision":"restricted_merchant","type":"predicate"}

{"abstain":true,"answer":true,"probability":0.62,"reasons":["mcc_5816","kind_sweepstakes_casino"],"decision":"restricted_merchant","type":"predicate"}

# Claude

In Claude Desktop, claude.ai and Claude Code you can ask closed questions about transactions, support messages and health plan member data and get a closed answer, a probability and an abstain flag back. The connector offers eleven tools, including three health tools that take derived numbers and presence flags only; they are not a diagnosis and not emergency help.

Not open yet. Opens with early access.

## Before you start

- claude.ai and Claude Desktop connect to the hosted server with a custom connector. Custom connectors are documented for Pro, Max, Team and Enterprise, and the Free plan can add one. On Team and Enterprise an Owner adds it for the organization, and members then connect it themselves.
- Claude Code works on any plan. It can send an API key in a header, or sign in.
- An Understanding account. Sign up if you have none. For Claude Code with a key, create the key in the console. The connector needs no key, because you sign in.

## Set it up

### claude.ai and Claude Desktop

1. Open Customize, then Connectors, then Add custom connector.
2. Name it `Understanding` and enter the URL `https://api.theunderstanding.company/mcp/claude`.
3. Choose to sign in. If Claude asks which OAuth client to use, choose Claude's published identity, or register automatically. The server supports both.
4. Choose Add, then Connect. A window opens on our sign-in page. Sign in with your Understanding account and Allow. The approval screen names the app by its address (`claude.ai`).
5. In a chat, open + and Connectors, and turn Understanding on.

On Team and Enterprise an Owner does step 2 under Organization settings, then Connectors, then Add, Custom, Web. Members then open Customize, then Connectors, and choose Connect. Claude does not let you edit a connector's sign-in settings after you add it. To change them, remove the connector and add it again.

### Claude Code

Add the hosted server with an API key from your environment:

```
claude mcp add --transport http understanding https://api.theunderstanding.company/mcp/claude \
  --header "Authorization: Bearer $UNDERSTANDING_API_KEY"
```

Add `--scope user` to use it in every project, or `--scope project` to write `.mcp.json`. The command above has your shell expand `$UNDERSTANDING_API_KEY`, so with `--scope project` the key itself would be written into `.mcp.json`, which is often committed. For a shared project, write the entry in `.mcp.json` by hand with the header as `Bearer ${UNDERSTANDING_API_KEY}`, which Claude Code expands from your environment, so no secret is committed. Check it with `claude mcp list` and, inside Claude Code, `/mcp`.

To sign in instead of using a key, leave out `--header`, then run `/mcp` inside Claude Code and choose to authenticate. Claude Code opens our sign-in page and receives the approval on a local address, which the server accepts on any port.

The plugin bundles the same connection with the agent skill. The skill is where the "when to call this, and what to do when it abstains" guidance lives, so the tool descriptions can stay short.

### Claude Desktop with an API key

The connector above signs you in. If you would rather paste a key, or want the Mac tools that read statement files on your computer, use the local package. Not open yet. Opens with early access. Then you add it to Claude Desktop's configuration file (Settings, Developer, Edit Config), with the absolute path to the package, and restart Claude:

```
{
  "mcpServers": {
    "understanding": {
      "command": "node",
      "args": ["/absolute/path/to/understanding-mcp/index.js"],
      "env": { "UNDERSTANDING_API_KEY": "usk_live_..." }
    }
  }
}
```

## What we tuned for this service

The `/mcp/claude` address is the standard server with these changes. They change wording and result shape only, never behavior or billing.

- Short descriptions that say what a tool does, not how Claude should behave. Anthropic's directory rules reject instructions inside a description, so none are there. The guidance lives in the skill.
- One compact JSON object per result, abstain first, with no second copy of the data. Claude Code caps how much a tool can return, and a compact result stays far under it.
- A real HTTP 401 with a sign-in challenge for a missing, expired or revoked credential, sent before any tool runs. A tool error inside a 200 does not start a sign-in in Claude; a 401 does.
- Every tool is marked read-only, idempotent and closed-world, and has a title. An abstain is a normal successful result.

## Check that it works

Ask Claude:

```
My statement has a charge from DRAFTKINGS with merchant category code 7995. Is that a restricted merchant?
```

Claude should ask to use Check restricted merchant (`check_restricted_merchant`) if it has not been allowed yet, then call it. The tool result is one JSON object:

```
{"abstain":false,"answer":true,"probability":0.97,"reasons":["mcc_7995","rule_gambling_category","kind_sportsbook"],"decision":"restricted_merchant","type":"predicate"}
```

A case that abstains looks like this, and Claude should tell you it is unsure instead of stating the answer as fact:

```
{"abstain":true,"answer":true,"probability":0.62,"reasons":["mcc_5816","kind_sweepstakes_casino"],"decision":"restricted_merchant","type":"predicate"}
```

The numbers show the format. They are not measured results.

## If it doesn't connect

- Claude says it cannot reach the server. Claude's servers make the request, not your computer. The address must be on the public internet over HTTPS. If the API sits behind a firewall for you, allow Anthropic's published outbound range, `160.79.104.0/21`.
- The sign-in window opens and fails. Claude sends the sign-in back to `https://claude.ai/api/mcp/auth_callback` (or `https://claude.com/api/mcp/auth_callback`). The server accepts both. Claude Code uses a local address on a port it picks. Check the approval screen: it should name `claude.ai`, `claude.com` or `localhost`.
- You changed the connector and nothing changed. Claude caches our sign-in metadata for about five minutes. Wait, or remove and re-add the connector.
- The Free plan only lets you add one connector.
- You only have a key and the connector asks for a sign-in. Some organizations have a beta in the Add custom connector dialog called Request headers, which sends a fixed header. It is limited to some organizations, shared by the whole organization and sent exactly as typed, so you would type `Bearer usk_live_...`. If you do not see it, use Claude Code or the local package.
- It worked, then stopped. Revoking the app under Connected apps in the console, or a refresh token used twice, ends the connection. Connect again.
- A tool returns `unauthorized`. The credential was rejected. Reconnect.

Source: /api/docs/integrations/claude