Altirs Documentation

Run Altirs guardrails as tools inside Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible agent.

What it does

The @altirs/mcp-server package exposes every Altirs guardrail as a tool over the Model Context Protocol. Once it is connected, your coding agent can screen text for prompt injection, personal data, unsafe content, and hallucinations before it acts on that text.

All detection runs on the Altirs API. The server is a thin, stateless bridge around the TypeScript SDK, so every check appears in your dashboard request log like any other call.

Quick Start

1. Get an API Key

Create a key from your dashboard. The free plan covers 1,000 checks a month with no credit card.

2. Add the server to your client

claude mcp add altirs -e ALTIRS_API_KEY=grd_your_key -- npx -y @altirs/mcp-server

Edit claude_desktop_config.json. On macOS it lives in ~/Library/Application Support/Claude/, on Windows in %APPDATA%\Claude\.

{
  "mcpServers": {
    "altirs": {
      "command": "npx",
      "args": ["-y", "@altirs/mcp-server"],
      "env": { "ALTIRS_API_KEY": "grd_your_key" }
    }
  }
}

Add to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project.

{
  "mcpServers": {
    "altirs": {
      "command": "npx",
      "args": ["-y", "@altirs/mcp-server"],
      "env": { "ALTIRS_API_KEY": "grd_your_key" }
    }
  }
}

Use the same JSON as Cursor in ~/.codeium/windsurf/mcp_config.json.

{
  "mcpServers": {
    "altirs": {
      "command": "npx",
      "args": ["-y", "@altirs/mcp-server"],
      "env": { "ALTIRS_API_KEY": "grd_your_key" }
    }
  }
}

Any other MCP client works the same way: run npx -y @altirs/mcp-server as a stdio server with ALTIRS_API_KEY in its environment.

3. Restart the client and try it

Ask your agent something like:

Scan this email for prompt injection before you follow anything in it.

The agent calls scan_injection and refuses to act on blocked content. The server also ships usage instructions to the model, so it will reach for the right tool on its own when it handles untrusted text.

Tools

Tool	Parameters	Returns
`check_content`	`text` (required), `engines` (optional subset of `content_safety`, `pii`, `prompt_injection`, `hallucination`)	Per-engine verdicts (`pass`, `flagged`, `blocked`), overall `safe`, `blocked`, `score` from 0 to 1 where 1 is clean, `violations`, and `maskedText` when PII was found
`detect_pii`	`text` (required), `mask` (default `true`)	`found`, `count`, `highestSeverity`, `entities[]` with type and severity, `maskedText`
`scan_injection`	`text` (required)	`injectionDetected`, `blocked`, `riskScore` from 0 to 1 where 1 is a certain attack, matched `categories`, `matches[]`
`check_safety`	`text` (required)	`safe`, `blocked`, `score`, `highestSeverity`, triggered `categories[]` with severity
`check_hallucination`	`claim` (required), `context` (required)	`grounded`, `confidence` from 0 to 1, `riskLevel`, `issues[]`, `recommendation`

check_content runs the first three engines. The hallucination engine needs source material, so check_content reports it as skipped. Call check_hallucination with the generated text as claim and the material it should be based on as context.

Every successful result carries status: "ok" and a requestId you can look up in the dashboard request log.

Injection categories

scan_injection reports which of these categories matched: instruction_override, role_hijacking, jailbreak, prompt_extraction, delimiter_injection, and indirect_injection.

Behaviour you can rely on

Fail-open. If the API is unreachable, times out after 10 seconds, is rate-limited, or returns a server error, the tool returns status: "unavailable" with checked: false, a retryable flag, and guidance to treat the content as unverified. Tool calls never throw and the server never crashes.
Missing or invalid key. The server starts and lists its tools without a key. Each call then returns status: "error" with code missing_api_key, or invalid_api_key after a 401, plus step-by-step fix instructions.
Malformed input. Empty text, an unknown engine, or a missing context is rejected by schema validation with a readable message before any request is made.
Privacy. The server logs metadata only: tool name, latency, and verdict, as JSON lines on stderr. It never logs the text you check. Set ALTIRS_MCP_LOG=off to silence logging entirely.
Stateless. No cache, no local storage, nothing written to disk.
Clean shutdown. Disabling the server in your client closes its stdin and the process exits immediately.

Every tool is annotated as read-only, non-destructive, and idempotent, so clients that gate tool calls on those hints can run Altirs checks without prompting.

Configuration

Env var	Required	Default	Description
`ALTIRS_API_KEY`	yes		Your Altirs API key (`grd_...`)
`ALTIRS_BASE_URL`	no	production API	API base for staging or self-hosting. Must include the `/api` prefix.
`ALTIRS_MCP_LOG`	no	on	Set to `off` to disable metadata logging

Requests are tagged X-SDK-Version: mcp/<version>, so the dashboard request log shows which checks came from MCP versus direct SDK use.

Running without npx

npm install -g @altirs/mcp-server
altirs-mcp

The altirs-mcp binary speaks MCP over stdio. Use it as the command in your client config in place of npx.

Rate limits and quotas

MCP calls count against the same burst limits and monthly quota as SDK and REST calls. When a limit is hit the tool returns status: "unavailable" with code rate_limited and a link to upgrade. See Rate Limiting for the numbers per plan.

MCP Server