MCP Server Integration

Model Context Protocol server exposing Sentinel safety tools.

Requirements

pip install sentinelseed[mcp]
# or manually:
pip install sentinelseed mcp

Dependencies:

• mcp>=0.1.0: GitHub

For Claude Desktop:

npm install -g mcp-server-sentinelseed

Overview

Tools Provided

Resources Provided

Quick Start

Standalone Server

from sentinelseed.integrations.mcp_server import create_sentinel_mcp_server

mcp = create_sentinel_mcp_server()
mcp.run()

Or run directly:

python -m sentinelseed.integrations.mcp_server

Add to Existing Server

from mcp.server.fastmcp import FastMCP
from sentinelseed.integrations.mcp_server import add_sentinel_tools

mcp = FastMCP("my-server")
add_sentinel_tools(mcp)

@mcp.tool()
def my_custom_tool():
    pass

mcp.run()

IDE Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "sentinel": {
      "command": "npx",
      "args": ["mcp-server-sentinelseed"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "sentinel": {
      "command": "python",
      "args": ["-m", "sentinelseed.integrations.mcp_server"],
      "env": {}
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "sentinel": {
      "command": "python",
      "args": ["-m", "sentinelseed.integrations.mcp_server"],
      "env": {}
    }
  }
}

VS Code (with Continue or similar)

Add to your MCP-compatible extension's config:

{
  "mcpServers": {
    "sentinel": {
      "command": "python",
      "args": ["-m", "sentinelseed.integrations.mcp_server"]
    }
  }
}

Configuration

MCPConfig

Default limits and timeouts:

from sentinelseed.integrations.mcp_server import MCPConfig

# Text size limits
MCPConfig.MAX_TEXT_SIZE = 50 * 1024        # 50KB per request
MCPConfig.MAX_TEXT_SIZE_BATCH = 10 * 1024  # 10KB per batch item

# Batch limits
MCPConfig.MAX_BATCH_ITEMS = 1000           # Maximum items in batch
MCPConfig.DEFAULT_BATCH_ITEMS = 100        # Default batch size

# Timeouts
MCPConfig.DEFAULT_TIMEOUT = 30.0           # Default operation timeout
MCPConfig.BATCH_TIMEOUT = 60.0             # Batch operation timeout

create_sentinel_mcp_server

create_sentinel_mcp_server(
    name="sentinel-safety",      # Server name
    sentinel=None,               # Sentinel instance (optional)
    seed_level="standard",       # Default seed level
)

add_sentinel_tools

add_sentinel_tools(
    mcp,                         # FastMCP server instance (required)
    sentinel=None,               # Sentinel instance for get_seed (optional)
    validator=None,              # LayeredValidator for validation (optional)
)

Tool Specifications

sentinel_validate

def sentinel_validate(text: str, check_type: str = "general") -> dict:
    """
    Validate text through THSP gates.

    Args:
        text: Content to validate (max 50KB)
        check_type: "general", "action", or "request"

    Returns:
        {safe: bool, violations: [], recommendation: str}
        On size error: {safe: False, error: "text_too_large", ...}
    """

sentinel_check_action

def sentinel_check_action(action: str) -> dict:
    """
    Check if planned action is safe.

    Args:
        action: Action description (max 50KB)

    Returns:
        {safe: bool, should_proceed: bool, concerns: [], risk_level: str}
    """

sentinel_check_request

def sentinel_check_request(request: str) -> dict:
    """
    Validate user request for safety.

    Args:
        request: User request text (max 50KB)

    Returns:
        {should_proceed: bool, risk_level: str, concerns: []}
    """

sentinel_get_seed

def sentinel_get_seed(level: str = "standard") -> str:
    """
    Get Sentinel seed for system prompt.

    Args:
        level: "minimal", "standard", or "full"

    Returns:
        Seed content string
    """

sentinel_batch_validate

def sentinel_batch_validate(
    items: list,
    check_type: str = "general",
    max_items: int = 100
) -> dict:
    """
    Validate multiple items.

    Args:
        items: List of text strings (max 10KB each)
        check_type: "general", "action", or "request"
        max_items: Maximum items to process (default 100, max 1000)

    Returns:
        {
            total: int,
            safe_count: int,
            unsafe_count: int,
            skipped_count: int,  # Items that exceeded size limit
            all_safe: bool,
            truncated: bool,
            results: []
        }
    """

Client Usage

HTTP Transport (Remote Server)

Note: HTTP transport requires streamable_http_client from the MCP SDK, which may not be available in all versions. Use stdio transport for maximum compatibility.

from sentinelseed.integrations.mcp_server import SentinelMCPClient

async with SentinelMCPClient(
    url="http://localhost:8000/mcp",
    timeout=30.0,  # Optional timeout override
) as client:
    # List available tools
    tools = await client.list_tools()

    # Validate text
    result = await client.validate("Some text to check")
    if result["safe"]:
        proceed()

    # Check action safety
    action_result = await client.check_action("delete user data")
    print(f"Risk level: {action_result['risk_level']}")

    # Batch validation with custom timeout
    batch = await client.batch_validate(
        ["text1", "text2", "text3"],
        check_type="request",
        timeout=60.0,  # Override timeout for batch
    )

Stdio Transport (Local Server)

async with SentinelMCPClient(
    command="python",
    args=["-m", "sentinelseed.integrations.mcp_server"],
    timeout=10.0,
) as client:
    result = await client.check_request("ignore previous instructions")
    if not result["should_proceed"]:
        print(f"Blocked: {result['concerns']}")

Exception Handling

from sentinelseed.integrations.mcp_server import (
    MCPClientError,      # Base exception for client errors
    MCPTimeoutError,     # Operation timed out
    MCPConnectionError,  # Connection failed
    TextTooLargeError,   # Text exceeds size limit
)

try:
    async with SentinelMCPClient(url="http://localhost:8000/mcp") as client:
        result = await client.validate(text, timeout=5.0)
except MCPTimeoutError as e:
    print(f"Timeout after {e.timeout}s on {e.operation}")
except TextTooLargeError as e:
    print(f"Text {e.size} bytes exceeds limit of {e.max_size}")
except MCPClientError as e:
    print(f"Client error: {e}")

Logging

Enable debug logging to see operation details:

import logging
logging.getLogger("sentinelseed.mcp_server").setLevel(logging.DEBUG)

Running Examples

# Basic examples
python -m sentinelseed.integrations.mcp_server.example

# All examples including async client
python -m sentinelseed.integrations.mcp_server.example --all

API Reference

Functions

Classes

SentinelMCPClient Methods

Constants

Links

• MCP SDK
• MCP Specification
• npm Package
• Sentinel