# MCP Server

Part of the HebrewCore documentation. Web: https://hc.itsbaba.com/docs#mcp · Whole docs: https://hc.itsbaba.com/docs.md · Index: https://hc.itsbaba.com/llms.txt

HebrewCore is also a remote [Model Context Protocol](https://modelcontextprotocol.io) server, so AI agents and assistants can call every capability as a tool. Each tool call runs the matching REST endpoint with your key, so validation, rate limits, the monthly character quota, account terms and Clinical access work exactly as they do over REST.

| Setting | Value |
| --- | --- |
| Endpoint | `https://hc.itsbaba.com/mcp` |
| Transport | Streamable HTTP (JSON responses, no session). Protocol versions `2026-07-28`, `2025-11-25`, `2025-06-18` and `2025-03-26`. |
| Authentication | Your API key as the header `Authorization: Bearer hc_live_…`. Listing the tools works without a key; calling one needs it. |
| Server card | [`/.well-known/mcp.json`](https://hc.itsbaba.com/.well-known/mcp.json) (also at `/.well-known/mcp/server-card.json`) |
| Registry name | `com.itsbaba/hebrewcore` |

## Tools

| Tool | What it does |
| --- | --- |
| `translate` | One text between Hebrew, English, Russian and more, with protected values, domains, gender and ICU plurals |
| `translate_batch` | Up to 50 strings to one target language |
| `analyze_direction` | RTL/LTR structure and display runs of a string or a record (free) |
| `detect_language` | Dominant language, script and per-language segments (free) |
| `wrap_for_display` | Render-ready HTML, isolates or marks for one display line (free) |
| `transliterate` | Hebrew to Latin letters, or Latin spelling to Hebrew letters |
| `add_nikud` | Full vowel points, verified |
| `strip_nikud` | Remove nikud and cantillation (free) |
| `list_languages` | Supported languages and their codes (free) |
| `list_terms` | The account's protected terms (free) |
| `add_terms` | Add or update protected terms (free) |
| `delete_term` | Delete one protected term (free) |
| `clinical_translate` | Clinical English to verified Hebrew (Clinical access) |
| `clinical_query` | Hebrew clinical question to an English record query (Clinical access) |
| `clinical_verify` | Check Hebrew against its English clinical source (Clinical access) |
| `health` | Service health; needs no key |

Tools marked free use no characters; the rest use the monthly character quota like the endpoint they call. Protected values (prices, amounts, account numbers, dates, doses, codes, product names) come back exactly as written, and the server tells the agent not to change them. API errors such as `quota_exceeded`, `rate_limited` or `scope_required` come back as tool errors with the same message.

## Claude Code

```text
claude mcp add --transport http hebrewcore https://hc.itsbaba.com/mcp \
  --header "Authorization: Bearer hc_live_YOUR_KEY"
```

## Claude Desktop and claude.ai

The server authenticates with a static API key, and Claude custom connectors that only offer OAuth cannot send it. Connect Claude Desktop through `mcp-remote`, which adds the header. In `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "hebrewcore": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://hc.itsbaba.com/mcp", "--header", "Authorization:${HC_AUTH}"],
      "env": { "HC_AUTH": "Bearer hc_live_YOUR_KEY" }
    }
  }
}
```

The same `mcp-remote` setup works for any client that cannot send a header itself.

## Cursor

In `~/.cursor/mcp.json` or the project's `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "hebrewcore": {
      "url": "https://hc.itsbaba.com/mcp",
      "headers": { "Authorization": "Bearer hc_live_YOUR_KEY" }
    }
  }
}
```

## VS Code

In `.vscode/mcp.json`. VS Code asks for the key once and stores it securely:

```json
{
  "inputs": [
    { "type": "promptString", "id": "hebrewcore-key", "description": "HebrewCore API key", "password": true }
  ],
  "servers": {
    "hebrewcore": {
      "type": "http",
      "url": "https://hc.itsbaba.com/mcp",
      "headers": { "Authorization": "Bearer ${input:hebrewcore-key}" }
    }
  }
}
```

## OpenAI API and Agents SDK

As a remote MCP tool in the Responses API:

```text
from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-5.5",
    tools=[{
        "type": "mcp",
        "server_label": "hebrewcore",
        "server_url": "https://hc.itsbaba.com/mcp",
        "headers": {"Authorization": "Bearer hc_live_YOUR_KEY"},
        "require_approval": "never",
    }],
    input="Translate 'Your order of 3 items ships on 04/03/2026' into Hebrew, keeping the date and quantity exact.",
)
print(response.output_text)
```

With the OpenAI Agents SDK (Python):

```text
from agents import Agent, HostedMCPTool

agent = Agent(
    name="Hebrew assistant",
    tools=[HostedMCPTool(tool_config={
        "type": "mcp",
        "server_label": "hebrewcore",
        "server_url": "https://hc.itsbaba.com/mcp",
        "headers": {"Authorization": "Bearer hc_live_YOUR_KEY"},
        "require_approval": "never",
    })],
)
```

> Keep the key on your side: in a config file on your machine, a secret store, or your server. Never put it in a prompt, a shared configuration or browser code. Clinical tools also need a key with Clinical access and refuse calls that come from a browser.