resk-mcp · Documentation

Secure Model Context Protocol layer

resk-mcp (PyPI: mcp-resk) wraps Python MCP servers with authentication, request screening, rate limiting, token budgets and audit tracking — without replacing the official Model Context Protocol SDK.

• Version 0.1.4
• Python 3.11+
• MIT license
• Import name: resk_mcp

What resk-mcp does

An MCP server is not an ordinary internal API. The caller is a language model that discovers tools at runtime and invokes them semi-autonomously, so the usual assumptions — a human on the other end, a stable capability set, structured payloads only — do not hold. resk-mcp adds the controls that assumption gap requires, on top of the official mcp Python SDK:

• It pins down who is calling. Every request to the secured endpoint must carry a valid JWT signed with your server's secret; the user_id claim becomes the identity used for rate limiting and logs.
• It pins down how much. Per-caller rate limits (via slowapi) and a per-request token budget (via a token estimator) bound the work a single client can trigger.
• It screens what crosses the boundary. Parameters are validated against a Pydantic schema, then scanned for prompt-injection phrases and personally identifiable information before any tool runs.
• It records everything. Calls to tools, resources and prompts are counted per name and exposed through a web dashboard and a JSON API.

The library does not reimplement MCP. It subclasses FastMCP, keeps your existing tools, resources and prompts, and mounts a secured dispatcher on the FastAPI app at /mcp_secure.

How a request flows

client ── POST /mcp_secure ──▶ rate limit (slowapi)
                                  │
                                  ▼
                            Bearer token present?
                                  │
                                  ▼
                            verify_jwt_token()  ── invalid ──▶ -33000 AUTH_ERROR
                                  │
                                  ▼
                            payload shape (Pydantic)
                                  │
                                  ▼
                      detect_prompt_injection(params) ── hit ──▶ -33003
                      detect_pii(params)             ── hit ──▶ -33003
                      context_manager.is_within_limits ── over ──▶ -33002
                                  │
                                  ▼
                        dispatch: tool/<name> · resource/<name> · prompt/<name>
                                  │
                                  ▼
                        counter++ (dashboard)  →  JSON-RPC result

Detection order matters when you debug a rejection: the HTTP rate limiter runs first (it is a FastAPI dependency on the route), then authentication, then payload validation, then the injection/PII/context checks. Details are on the security model page.

Feature summary

Quick start

Install the package, export one secret, register a tool and start the server:

1. Install and create .env:

   pip install mcp-resk
   
   # .env (never commit this file)
   JWT_SECRET="$(python -c 'import secrets; print(secrets.token_urlsafe(48))')"

2. Write main.py:

   from resk_mcp import SecureMCPServer, create_jwt_token
   
   server = SecureMCPServer(name="my-secure-mcp")
   
   @server.tool(name="calculator/add")
   async def add(a: int, b: int) -> int:
       """Adds two numbers."""
       return a + b
   
   if __name__ == "__main__":
       print("Bearer", create_jwt_token(user_id="[email protected]"))
       server.run_server(port=8001)

3. Call the secured endpoint with the token printed at startup:

   curl -s http://localhost:8001/mcp_secure \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"id":1,"method":"tool/calculator/add","params":{"a":2,"b":3}}'

4. Enable the dashboard (DASHBOARD_AUTH_ENABLED=true plus a non-default DASHBOARD_PASSWORD) and open http://localhost:8001/dashboard to watch the interaction counters. It returns 404 while disabled — by design.

HTTP surface

The FastAPI-generated /docs, /redoc and /openapi.json routes are disabled by default because they publish the full tool schema. Set RESK_MCP_DOCS=true only in a trusted environment.

Scope and limitations

Being precise about the boundary is part of the design:

• In-process, not a gateway. resk-mcp is a Python library you embed in your server. It does not proxy third-party MCP servers, and it cannot protect a server you do not control.
• Detection is basic by design. PII and prompt-injection checks are pattern-based. They catch the common cases and are meant to be one layer, not the only one — pair them with model-side filtering (for example resk-llm on the client side) and normal application authorization.
• Requests are screened, not responses. Tool output can still carry injected instructions into the model context; filter it on the consumer side or with MCPSecurityManager.check_response() (see the API reference).
• No built-in token issuance service. You mint tokens with create_jwt_token() or your own identity provider, using the same secret and algorithm.

Where to go next