MCP Server Integration

OGuardAI provides an MCP (Model Context Protocol) server compatible with any MCP client, including Claude Desktop, Claude Code, Cursor, Windsurf, and other tools that support the protocol.

Install

npm install -g @oguardai/mcp-server
# or
pnpm add -g @oguardai/mcp-server

Desktop Client Configuration

Example for Claude Desktop (other MCP clients use similar JSON config):

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "guardai": {
      "command": "guardai-mcp",
      "args": [],
      "env": {
        "GUARDAI_URL": "http://localhost:3000",
        "GUARDAI_API_KEY": "your-api-key"
      }
    }
  }
}

Or run the server directly with npx:

{
  "mcpServers": {
    "guardai": {
      "command": "npx",
      "args": ["@oguardai/mcp-server"],
      "env": {
        "GUARDAI_URL": "http://localhost:3000"
      }
    }
  }
}

IDE / CLI MCP Clients

Add to your MCP client's server configuration (path varies by client; check your client's docs for the config file location):

{
  "mcpServers": {
    "guardai": {
      "command": "npx",
      "args": ["@oguardai/mcp-server"],
      "env": {
        "GUARDAI_URL": "http://localhost:3000"
      }
    }
  }
}

Available Tools

Once configured, the AI client has access to these tools.

By default the server exposes only the data tools. The five admin/ops tools (guardai_diagnostics, guardai_metrics, guardai_validate_policies, guardai_revocation_count, guardai_reload_policies) are hidden from tools/list and rejected at dispatch unless GUARDAI_MCP_EXPOSE_ADMIN is enabled, and guardai_revoke is gated separately behind GUARDAI_MCP_EXPOSE_REVOKE, so an operator can enable the ops surface without also handing a model-facing client the ability to revoke entities. The five admin/ops tools are additionally admin-scoped on the OGuardAI server itself, so exposing them here still requires an admin API key upstream. guardai_revoke instead needs the revoke scope, plus global_revoke when the upstream key has no tenant binding (both of which admin implies).

guardai_transform

Protect sensitive data in text by replacing PII with semantic tokens.

Parameters:

Example interaction:

User: "Please draft a reply to this customer email:
  From: Julia Schneider <julia@example.com>
  Subject: Order complaint ORD-2026-4892"

Claude (inside the MCP tool loop):
  1. Calls guardai_transform with the email text
     -> Gets safe text with {{person:p_001:6a3e91f04d27}}, {{email:e_001:c85b2df1e963}}, {{order:o_001:41f7a9c0b3d5}}
  2. Drafts reply using the semantic tokens (no raw PII seen by the model)

Host application (AFTER the agent/model finishes):
  3. Calls guardai_rehydrate with the model's tokenized output
     and the session_state from step 1
     -> Restores real values server-side for delivery to the end user

NOTE: guardai_rehydrate is NOT called by the model as an MCP tool.
It is called by the host application code after the model loop ends.
The model never sees restored PII.

guardai_rehydrate

Resolve OGuardAI semantic tokens server-side and report resolution metadata (tokens_resolved, tokens_unresolved). The restored text is deliberately NOT returned to the model context; the host application calls /v1/rehydrate directly to obtain restored_text.

Important: This tool is intended to be called by the host application OUTSIDE the model/MCP tool loop, not by the model itself. The model calls guardai_transform during reasoning, but rehydration happens after the agent finishes, in the host code. This ensures the model never sees restored PII.

Parameters:

guardai_detect

Detect entities in text without transforming. Useful for auditing and understanding what PII exists in content.

Parameters:

guardai_health

Check the OGuardAI server health status.

guardai_evaluate_policy

Evaluate what a policy would do to detected entities without actually transforming.

Parameters:

guardai_capabilities

List what the runtime supports: entity types, languages, detectors, restore modes, and limits (for example the max batch size). Returns no PII. Use it to discover what can be detected before transforming. No parameters.

guardai_diagnostics

Get the runtime configuration and health snapshot: detector mode, loaded policies, auth mode, session backend, and feature flags. Returns no PII. Admin/ops scoped server-side, so it fails for a non-admin key. Exposed only when GUARDAI_MCP_EXPOSE_ADMIN is enabled. No parameters.

guardai_validate_policies

Validate a server-side policy directory without loading it: reports whether every policy parses and what would change versus the active set. Returns no PII. Admin/ops scoped server-side. Exposed only when GUARDAI_MCP_EXPOSE_ADMIN is enabled.

Parameters:

guardai_reload_policies

Hot-reload the server policy directory from disk and report what changed versus the active set: the reloaded flag, policies_loaded, policy_names, and the changes. Returns no PII. Admin/ops scoped server-side. Exposed only when GUARDAI_MCP_EXPOSE_ADMIN is enabled. No parameters.

guardai_batch_transform

Transform many texts in one call. Each result carries tokenized safe_text and its own session_state. Only tokenized output is returned, never raw PII.

Parameters:

guardai_batch_detect

Detect PII entities across many texts at once. Returns entity types and spans only, never raw values. Pass a policy (global or per item) to apply that policy's custom detectors and NER labels.

Parameters:

guardai_revoke

Right to erasure: revoke a specific PII value for the tenant, so any later rehydrate resolves its token to [DELETED]. Returns counts and status only; the raw value is never echoed back. Exposed only when GUARDAI_MCP_EXPOSE_REVOKE is enabled.

Parameters:

guardai_revocation_count

Return the number of revoked entity values in the caller's own scope, an erasure-operations metric. Aggregate count only, no PII. Requires the admin scope server-side, so it fails for a non-admin key; a tenant-scoped admin key returns its own tenant's count, never a cross-tenant total. Exposed only when GUARDAI_MCP_EXPOSE_ADMIN is enabled. No parameters.

guardai_metrics

Return the server Prometheus metrics: operation counts, per-type entity counts, and latency series. Admin/ops scoped server-side. Returns no PII. Exposed only when GUARDAI_MCP_EXPOSE_ADMIN is enabled. No parameters.

guardai_rag_ingest

Ingest a document for RAG: split it into chunks and replace PII with tokens. Returns tokenized safe chunks (store these in the vector DB) plus a session_state. Set corpus_id for stable cross-document token identity.

Parameters:

guardai_rag_query

Transform a user query for RAG retrieval: returns the tokenized safe_query (use it for vector search) and a session_state. Pass the same corpus_id used at ingest so query tokens align with the ingested document tokens.

Parameters:

guardai_rag_context

Assemble retrieved chunks into a safe LLM context, merging each document's tokens. Returns tokenized safe_chunks and a session_state. Pass document_sessions (the chunk_session_state from ingest, parallel to chunks) so document-only entities resolve in the answer.

Parameters:

guardai_rag_answer

Validate that an LLM answer's tokens resolve against the context session. Returns metadata only (token counts). The restored answer with real PII is NOT returned; the host application must call /v1/rag/answer directly to retrieve it, the same host-side rehydrate pattern as guardai_rehydrate.

Parameters:

guardai_rag_delete

Forget every value in the given session: each is revoked for the tenant so later rehydrates resolve it to [DELETED]. To erase one document, pass that document's ingest session_state. Returns counts only. This backs GDPR erasure.

Parameters:

guardai_session_status

Report a session's lifecycle state (active or stateless) and backend. Identify the session by exactly one of session_id (memory or redis backend) or session_state (sealed backend). A missing or cross-tenant session returns a non-disclosing not-found. Returns no PII.

Parameters:

guardai_session_delete

Invalidate a server-held session so it can no longer be rehydrated. Identify it by exactly one of session_id or session_state. The sealed backend holds no server-side state, so it reports deleted: false. This does NOT revoke the mapped entity values; use guardai_revoke or guardai_rag_delete for right-to-erasure. Returns no PII.

Parameters:

Usage Examples

Protecting Customer Data in Conversations

User: "Summarize this customer complaint. Make sure to protect
their personal data:

  My name is Marcus Weber, email m.weber@techcorp.de.
  Order Q-2026-0847 was delivered damaged."

Claude will (inside the MCP tool loop):
1. Call guardai_transform to tokenize the PII
2. Process the safe text to generate a summary using tokens

Then the host application (AFTER the model loop ends):
3. Call guardai_rehydrate with the model's tokenized summary
   and the session_state, restoring real values for the end user.
   The model never calls guardai_rehydrate and never sees restored PII

Auditing Text for PII

User: "Check this document for any PII before I send it to the
external analytics team."

Claude will:
1. Call guardai_detect to find all entities
2. Report what was found (types, confidence scores)
3. Suggest which policy to apply

Environment Variables

The exposure flags accept 1, true, yes, or on (case-insensitive).