Palaryn MCP Server

Agent I/O governance for every HTTP request your AI agent makes — exposed as an MCP server.

Palaryn MCP wraps the Palaryn gateway as a Model Context Protocol server, giving Claude Code, Cursor, Windsurf, and any MCP-compatible client policy-enforced access to external APIs with zero code changes.

---

What It Does

Every HTTP request your AI agent makes flows through the Palaryn pipeline:

Claude Code / Cursor / MCP Client
        |
        | stdio (JSON-RPC 2.0) or HTTP (/mcp)
        v
  Palaryn MCP Server
        |
        +---> Rate Limiting     (per-actor sliding window)
        +---> Anomaly Detection (statistical outlier flagging)
        +---> Policy Engine     (YAML rules: allow / deny / require approval)
        +---> DLP Scanner       (secrets, PII, 119 detection patterns)
        +---> Prompt Injection  (3-layer cascade: regex → DeBERTa → LLM)
        +---> Call Limits       (per-user / workspace daily & monthly caps)
        +---> HTTP Execution    (retries, backoff, SSRF protection)
        +---> Output DLP Scan   (response body scanning)
        +---> Audit Logging     (immutable append-only trace)
        |
        v
   External API

Three MCP tools exposed:

Tool	Method	Capability	Description
http_request	Any	Inferred	Execute any HTTP request (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
http_get	GET	read	GET request shorthand
http_post	POST	write	POST request shorthand

Each tool accepts: url (required), headers, body, timeout_ms, purpose, labels.

---

Quick Start

Option 1: Hosted (requires a Palaryn account)

claude mcp add --transport http palaryn https://app.palaryn.com/mcp

Done. All requests from Claude Code now route through Palaryn. You will be prompted to log in via OAuth on first use.

Option 2: Project-level config

Create .mcp.json in your project root (see .mcp.json.example):

{
  "mcpServers": {
    "palaryn": {
      "type": "stdio",
      "command": "npx",
      "args": ["palaryn-mcp"],
      "env": {
        "POLICY_PACK_PATH": "./policy-packs/default.yaml"
      }
    }
  }
}

Note: Ensure palaryn-mcp is installed (e.g., via npm install palaryn-mcp) so npx can resolve it.

---

Configuration

Environment Variables

Variable	Default	Description
PALARYN_MCP_WORKSPACE	ws-claude-code	Workspace ID for tool calls
PALARYN_MCP_ACTOR	claude-code	Actor ID for audit trails
PALARYN_MCP_PLATFORM	claude_code	Platform identifier
POLICY_PACK_PATH	./policy-packs/default.yaml	Path to the active policy pack

Custom Policy Pack

Pass a custom policy via environment variable:

claude mcp add palaryn \
  -e POLICY_PACK_PATH=./policy-packs/prod_strict.yaml \
  -- node bin/palaryn-mcp.js

---

Policy Packs

Three pre-built policy packs are included:

default.yaml -- Sensible starter rules

• Block SSRF (cloud metadata endpoints)
• Allow all read operations (GET)
• Require human approval for writes (POST/PUT/PATCH)
• Deny delete and admin operations

dev_fast.yaml -- Permissive for development

• Block SSRF
• Allow reads and writes without approval
• Require approval for delete/admin operations

prod_strict.yaml -- Minimal permissions for production

• Block SSRF + internal IPs + localhost
• Allow reads only to allowlisted domains (e.g., api.github.com, api.slack.com)
• Require security review for all writes
• Deny all delete and admin operations
• Require admin approval for anything unmatched

Custom Policy Example

name: my-policy
version: "1.0.0"
description: "Custom policy for my project"

domain_blocklist:
  - "169.254.169.254"

rules:
  - name: "Allow GitHub API"
    effect: ALLOW
    priority: 10
    conditions:
      capabilities: ["read"]
      domains: ["api.github.com"]

  - name: "Require approval for writes"
    effect: REQUIRE_APPROVAL
    priority: 20
    conditions:
      capabilities: ["write"]
    approval:
      scope: "admin"
      ttl_seconds: 3600
      reason: "Write operations require approval"

  - name: "Deny everything else"
    effect: DENY
    priority: 100
    conditions: {}

---

How It Works

Architecture

Palaryn MCP server is a thin adapter layer that translates MCP tool calls into the Palaryn gateway pipeline:

MCP Client (Claude Code, Cursor, etc.)
     |
     | JSON-RPC 2.0 over stdio
     v
+-----------------------------+
|   Palaryn MCP Server        |
|                             |
|  tools/list -> 3 HTTP tools |
|  tools/call -> Gateway      |
+-----------------------------+
     |
     v
+-----------------------------+
|   Palaryn Gateway Pipeline  |
|                             |
|  1. Rate Limiting           |
|  2. Anomaly Detection       |
|  3. Policy Evaluation       |
|  4. DLP Scan (input)        |
|  5. Prompt Injection (3L)   |
|  6. Call Limit Check        |
|  7. HTTP Execution          |
|  8. DLP Scan (output)       |
|  9. Audit Logging           |
+-----------------------------+
     |
     v
   External API

MCP Protocol

The server implements the Model Context Protocol specification:

Method	Description
initialize	Protocol handshake -- returns server info and capabilities
tools/list	Returns the 3 HTTP tool definitions with JSON schemas
tools/call	Executes a tool through the gateway pipeline
ping	Health check

Two Transport Modes

Mode	Protocol	Best For
Stdio	JSON-RPC 2.0 over stdin/stdout	Claude Code, Cursor, local IDE agents
HTTP	Streamable HTTP at /mcp	Hosted/remote deployment, shared servers

Response Format

Every tool call returns two content blocks:

1. Primary content: The actual HTTP response body (or error message)
2. Gateway metadata: Policy decision, DLP report, call limits, timing

{
  "content": [
    { "type": "text", "text": "{\"data\": \"response from API\"}" },
    { "type": "text", "text": "--- Gateway Metadata ---\n{...}" }
  ],
  "isError": false
}

---

Security Features

Prompt Injection Detection (3-Layer Cascade)

Three-layer defense against prompt injection attacks, evaluated in cascade (fast layers first, expensive layers only if needed):

1. Regex + Heuristic (sync, <1ms, $0) — 119 patterns across 17 categories with text normalization (zero-width char stripping, homoglyph collapse, ROT13/base64 decoding, leetspeak, HTML/URL decoding). Multilingual: EN, PL, DE, ES, FR.
2. Fine-tuned DeBERTa (sync, ~50ms, $0) — Local ML model for semantic classification. URL-aware scanning (extracts query param values, ignores URL structure). Zero API cost, works offline.
3. LLM Classifier (async, ~800ms, ~$0.001/req) — Semantic classification via gpt-4o-mini. Detects 12 attack categories including instruction override, prompt extraction, roleplay hijack, social engineering, game manipulation, memory manipulation, data exfiltration, multilingual injection, compound attacks, and classifier self-manipulation.

Cascade logic: LLM only runs if Regex + DeBERTa find nothing — reducing API calls by ~35%.

DLP (Data Loss Prevention)

• 119 detection patterns: secrets (14), PII (5), prompt injection (65), tool injection (28), exfiltration (6), sensitive files (9)
• Scans request arguments AND response bodies
• Detects API keys, tokens, passwords, SSNs, credit card numbers, AWS credentials in URLs, markdown image injection, large payload exfiltration
• Automatically redacts sensitive data before it reaches external services
• Configurable severity levels and multiple detection backends

Policy Engine

• YAML-based policy rules with priority ordering
• Four decisions: ALLOW, DENY, TRANSFORM, REQUIRE_APPROVAL
• Conditions: capability level, HTTP method, target domain, tool name
• Domain blocklists for SSRF protection
• Optional OPA/Rego integration for advanced policy logic

SSRF Protection

• Blocks requests to cloud metadata endpoints (169.254.169.254, etc.)
• Blocks private/reserved IP ranges
• Integer-encoded IP detection (e.g., 2852039166 → 169.254.169.254)
• Domain allowlisting for production environments

Call Limits

• Per-user daily and monthly call limits
• Per-workspace daily and monthly call limits
• Max steps per task
• Prevents runaway loops from agent execution
• Real-time limit tracking with remaining calls in responses

Rate Limiting

• Sliding-window rate limiting per actor and per workspace
• Prevents abuse and ensures fair resource allocation

---

Integration Patterns

Claude Code

# Hosted (requires Palaryn account)
claude mcp add --transport http palaryn https://app.palaryn.com/mcp

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "palaryn": {
      "type": "stdio",
      "command": "npx",
      "args": ["palaryn-mcp"]
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "palaryn": {
      "serverUrl": "https://app.palaryn.com/mcp"
    }
  }
}

Remote MCP (HTTP)

For hosting Palaryn as a remote MCP server, the full gateway includes the /mcp HTTP endpoint with OAuth 2.0. Contact us at app.palaryn.com for access.

---

Tool Reference

http_request

Execute an arbitrary HTTP request through the Palaryn gateway.

Parameter	Type	Required	Description
url	string	Yes	Target URL
method	string	No	HTTP method (default: GET)
headers	object	No	HTTP headers as key-value pairs
body	string	No	Request body (typically JSON)
timeout_ms	number	No	Request timeout in milliseconds
purpose	string	No	Why this request is being made
labels	string[]	No	Classification labels

http_get

Shorthand for GET requests. Same parameters as http_request minus method and body.

http_post

Shorthand for POST requests. Same parameters as http_request minus method.

---

License

MIT