# Connecting MCP clients to Black Ice

> Connect Claude Desktop, Claude Code, Cursor, and other MCP clients to your Black Ice workspace to check approved terms and market availability live.

**Category:** AI Integrations | **Tab:** integrations

---

Connect Claude Desktop directly to your Black Ice workspace using the Model Context Protocol (MCP). Once connected, Claude can consult your ontology in real time — checking approved terms, flagging forbidden variants in draft translations, and confirming market availability — without you copying anything into the chat.

> **What you get.** Seven read-only governance tools (plus optional `suggest_candidates`, off unless your workspace turns it on), single-workspace per connection, authenticated by API key or OAuth 2.1. The MCP connector is available on **all plans**, including Free.

## Before you start

You will need:

1. A Black Ice workspace on **any plan** — Free, Pro, or Builder. There is no tier gate on the MCP connector itself; per-plan limits (concepts, markets, members) apply as normal.
2. **Claude Desktop** with custom-connector support enabled in Settings.
3. Five minutes.

## Step 1 — Generate an API key

1. Open Black Ice and go to **Settings → API Access**.
2. Click **Generate API key**, give it a recognisable name (for example, `Claude Desktop — laptop`), and copy the value.
3. The key starts with `bice_…` and is shown **only once**. Paste it somewhere safe before leaving the page.

> **Single-tenant, by design.** One key authorises one workspace. If you work across multiple Black Ice workspaces, generate a separate key for each and create a separate Claude Desktop connection per workspace.

## Step 2 — Add Black Ice as a custom connector in Claude Desktop

1. In Claude Desktop, open **Settings → Connectors → Add custom connector**.
2. Use the following configuration:

| Field | Value |
| --- | --- |
| Name | `Black Ice` |
| Remote MCP server URL | `https://mcp.black-ice.ai/mcp?apikey=YOUR_BICE_KEY` |
| Advanced settings | Leave OAuth Client ID and OAuth Client Secret empty |

> **Why a URL parameter?** Claude Desktop's custom connector UI does not currently support custom request headers, so the API key travels as a query parameter. Treat the full URL as a secret — anyone with it can read your workspace ontology. Header-based auth (`x-api-key`) remains the recommended path for programmatic clients (curl, MCP Inspector, custom integrations). OAuth 2.1 with Dynamic Client Registration is also available — see **What's next** below.

3. Save. Claude Desktop will run an `initialize` handshake and discover the seven tools (eight if candidate suggestions are on).

## Step 3 — Try each tool

Open a new Claude conversation and try one prompt per tool. The point of each prompt is to demonstrate something that a generic translator would not catch.

### `check_term` — see the governance metadata

> _"Use Black Ice to check the approved Spanish (`es-es`) term for **MIDI Editor**. Show me the forbidden variants too."_

Claude will return the approved term, status, market availability, and the `forbiddenVariants` list. The forbidden list is the part that matters: it's the vocabulary your team has explicitly ruled out.

### `validate_translation` — catch a forbidden variant in a draft

> _"Validate this Spanish draft against Black Ice: 'El nuevo MIDI Editor permite editar pistas con precisión.' Locale: `es-es`."_

If your workspace marks `MIDI Editor` as a forbidden variant for `es-es` (with `Editor MIDI` as the approved term), Claude will return a `forbidden`-severity flag pointing at the exact span and suggesting the approved replacement. This is the demo moment: the AI being told **"no, not that word."**

### `check_market_availability` — confirm a feature ships in a market

> _"Is the **Stem Splitter** feature available for the `es-es` market according to Black Ice? Include any tier or disclaimer constraints."_

Claude will return the availability state (`available`, `planned`, `not_available`, `unapproved`, `not_set`) and any market_constraint metadata you've recorded — tier, disclaimer, local plan name, supported platforms.

### `list_concepts` — discover what's in the ontology

> _"Using Black Ice, list all concepts available in `es-es` and tell me which ones are restricted by plan."_

Returns a slim list (`conceptId`, `conceptName`, `className`, `term`, `status`, `availability`) for every concept in the workspace ontology for the locale. Optional `class` filter narrows the list to a single class (`Feature`, `Plan`, `Market`, etc.). Useful as a first call before drilling into a specific concept with `check_term` or `check_market_availability`.

### `list_classes` — discover the workspace taxonomy

> _"Using Black Ice, what concept classes exist in this workspace for `es-es`?"_

Returns the distinct class names in the workspace ontology with concept counts, sorted by count descending. Recommended discovery flow: `list_classes` → `list_concepts(locale, class)` → `check_term` or `check_market_availability`. This makes prompts workspace-agnostic — no need to hardcode class names.

### `list_relationships` — traverse the semantic graph

> _"Using Black Ice, what concepts are part of `plan_00000001` in `es-es`?"_

Returns semantic relationships (`part_of`, `requires`, `variant_of`, etc.) between concepts. Inputs: `locale` (required), `conceptId` (optional — filter to relationships involving this concept), `direction` (optional — `outgoing`, `incoming`, or `both`; default `both`), `relationshipType` (optional — case-insensitive filter like `part_of`). Recommended graph traversal flow: `list_concepts(locale, class)` → pick a `conceptId` → `list_relationships(locale, conceptId)` to discover what it depends on, includes, or is part of.

### `get_market_profile` — voice, tone, and culture DNA for a locale

> _"Using Black Ice, what's the voice and tone profile for `es-es`?"_

Returns the full market profile for a locale: brand identity (name, tagline, positioning) plus the 10-section culture DNA — Market Snapshot, Voice/Locale DNA, Tone & Style Rules, Culture & Pragmatics, Grammar & Mechanics, UX/Microcopy Rules, Locale Conventions, Terminology Rules, Golden Examples, and Output Constraints. Use this to ground translation and content generation in the same market definition that drives Black Ice's in-app workflows. Input: `locale` (required, e.g. `es-es`). Returns `{ found: false }` if the locale is not configured for the workspace.

### `suggest_candidates` — send new terms to the review queue

```
Here are our new onboarding strings: <PASTE>. Check which product terms aren't in
Black Ice yet with list_concepts, then suggest them as candidates with a note on
where each one appears.
```

Off by default: an owner or admin must turn on **Allow AI assistants to suggest candidates** on the Integrations page. This is the only tool that writes, and it writes only to the [Candidates review queue](/docs/features/candidate-review-workflow). Your terminologist still runs the five tests and decides. It needs a **read-and-write** API key; read-only keys are refused.

## How disambiguation works

If a concept name resolves to more than one concept (for example, two classes both have a "Studio" concept), the tool returns:

```json
{
  "ambiguous": true,
  "matches": [
    { "conceptId": "feat_00000007", "conceptName": "Studio", "className": "Feature" },
    { "conceptId": "plan_00000003", "conceptName": "Studio", "className": "Plan" }
  ],
  "hint": "Multiple concepts share that name. Re-call this tool with the conceptId from `matches`."
}
```

Claude will follow up with the `conceptId` directly, bypassing name matching entirely.

## Troubleshooting

**"Missing or invalid x-api-key header"** — the connector URL is missing the `?apikey=bice_…` parameter, or the value doesn't start with `bice_`. Re-check the Remote MCP server URL.

**"No concept matched 'X' for locale 'Y'"** — either the concept doesn't exist in your workspace or no target term has been created yet for that locale. Check **Concepts** in Black Ice and confirm the locale has been added under **Markets**.

**Claude isn't suggesting Black Ice tools.** Add a system instruction to your Claude Project: _"When the user asks about a translation, terminology decision, or market availability, call Black Ice first."_

**Forbidden variant not flagged.** Only target terms with `status: approved` enforce. Pending or draft terms are ignored on purpose so in-progress edits don't generate noise. Approve the term in Black Ice and try again.

**Wrong workspace.** Each `bice_` key is bound to one workspace. If Claude returns the wrong terms, you've connected the key for a different workspace — generate a new key in the correct workspace.

## What's next

- **OAuth 2.1 with Dynamic Client Registration is live.** Clients that prefer OAuth over a static API key can discover the authorization server via `https://mcp.black-ice.ai/.well-known/oauth-protected-resource` and run the standard PKCE flow. Listing on the public Anthropic Connectors Directory is pending Anthropic review.
- A write API so Claude can propose new terms or flag drift directly into your workspace pending approval is on the roadmap.

## Other MCP clients

The endpoint is transport-agnostic Streamable HTTP and works with any MCP client. Claude Desktop is walked through above because its custom-connector UI cannot send custom headers, so the API key has to ride in the URL. Other clients should pass the key via the `x-api-key` header instead:

- **Claude Code** — `claude mcp add black-ice --transport http https://mcp.black-ice.ai/mcp --header "x-api-key: bice_…"`
- **Cursor** — add an MCP server in settings, point it at `https://mcp.black-ice.ai/mcp`, set `x-api-key` as a custom header.
- **MCP Inspector** — `npx @modelcontextprotocol/inspector` and configure the same endpoint + header.
- **Custom SDK clients** — any TypeScript or Python MCP SDK client; just include the `x-api-key` header on every request.

Both auth paths (`?apikey=` query param and `x-api-key` header) are accepted by the server. Use the header form whenever your client supports it — it keeps the key out of URL logs.


## Rate limits

All API and MCP calls are subject to per-plan throughput caps (Free 60 reads / 30 writes per minute, Pro 300 / 120, Builder 1,000 / 400). See [API & MCP rate limits](/docs/integrations/rate-limits) for headers, 429 handling, and pipeline design tips.