Skip to main content
Glama
secure-mcp-server

secure-mcp-server

by Srinath-VP

secure-mcp-server

A reference Model Context Protocol server that treats every AI agent as an untrusted caller. It shows the controls an enterprise MCP deployment needs before agents touch real systems:

  • Agent identity: every agent has its own short-lived JWT, so each call is tied to one named caller.

  • Least-privilege tools: a policy file grants one scope per tool. Unlisted tools are denied by default.

  • Tamper-evident audit log: every call, allowed or denied, is written as a hash-chained JSON line, with arguments redacted.

  • Input hardening: path-traversal and symlink-escape protection, size limits, strict ID formats, and no stack traces returned to the model.

  • Two transports: stdio for local clients and streamable HTTP with bearer auth for shared deployments.

The tools themselves (notes search, ticket CRUD) are deliberately simple. The value is in the layer around them.

How a call flows

flowchart LR
    A[AI agent / MCP client] -->|"Bearer JWT (HTTP) or MCP_AGENT_TOKEN (stdio)"| B[Token verifier]
    B -->|"identity + scopes"| C{Policy check<br/>policy.yaml}
    C -->|deny| L[(Audit log<br/>hash-chained JSONL)]
    C -->|allow| D[Tool with input validation]
    D --> L
    D -->|result| A
    C -.->|"error: access denied"| A

All tools go through one Guard.run() path in server.py. A tool cannot execute without a verified identity, a matching scope and an audit entry.

Related MCP server: ToolForge MCP Server

Threats this addresses

Risk (OWASP Top 10 for LLM Applications 2025)

Control here

LLM06 Excessive Agency: an agent calls tools it should not

Per-agent scopes, deny-by-default policy, destructive tools behind a separate admin scope

LLM01 Prompt Injection: injected text drives a tool call

Injected calls still need the token's scope; arguments are validated server-side, never trusted

LLM02 Sensitive Information Disclosure

Sandboxed file access, redacted audit arguments, generic error messages

Forged or replayed credentials

Pinned signing algorithm, iss/aud/exp checks, 1-hour maximum lifetime, unique jti per token

Covering tracks after misuse

Hash-chained audit log; verify-audit detects edited or deleted entries

Quick start

Requires Python 3.11+.

git clone https://github.com/Srinath-VP/secure-mcp-server.git
cd secure-mcp-server
pip install -e ".[dev]"

export MCP_JWT_SECRET="$(python -c 'import secrets; print(secrets.token_urlsafe(48))')"

Issue tokens for two agents with different privileges:

export READER_TOKEN=$(secure-mcp-server token --sub research-agent --scope notes:read)
export OPS_TOKEN=$(secure-mcp-server token --sub ops-agent --scope notes:read --scope tickets:write)

Run over streamable HTTP (clients send Authorization: Bearer <token>):

secure-mcp-server serve --transport http      # http://127.0.0.1:8000/mcp

Run over stdio (the agent's token comes from the environment):

MCP_AGENT_TOKEN=$READER_TOKEN secure-mcp-server serve --transport stdio

To use it from Claude Desktop or another MCP client over stdio, see examples/claude_desktop_config.json.

Check the audit trail:

secure-mcp-server verify-audit                # OK: 12 entries verified

Tools and scopes

Tool

Scope required

Notes

whoami

notes:read

Shows the identity and scopes on this connection

search_notes

notes:read

Searches Markdown files in sandbox/

read_note

notes:read

Reads one file; traversal and symlink escapes are refused

create_ticket

tickets:write

Ticket is owned by the calling agent

delete_ticket

tickets:admin

Marked destructiveHint so clients can ask for confirmation

Change access by editing policy.yaml, not code.

Audit log format

{"id": "9f2c…", "ts": 1762790400.123, "subject": "research-agent", "client_id": "research-agent",
 "token_id": "4be1…", "tool": "create_ticket", "arguments": {"title": "sha256:3a7bd3e2360a3d29"},
 "decision": "deny", "outcome": "denied", "duration_ms": 0.41,
 "detail": "tool 'create_ticket' requires scope 'tickets:write'",
 "prev_hash": "c1d0…", "hash": "77ae…"}

Argument values are fingerprinted, not stored, and keys such as token, password or api_key are replaced with [REDACTED]. You can still correlate calls without copying sensitive data into logs.

Configuration

Variable

Default

Purpose

MCP_JWT_SECRET

(required, 32+ chars)

HMAC key used to verify tokens

MCP_JWT_ISSUER / MCP_JWT_AUDIENCE

secure-mcp-dev / secure-mcp-server

Expected iss and aud claims

MCP_AGENT_TOKEN

Caller's token for the stdio transport

MCP_POLICY_PATH

policy.yaml

Tool-to-scope policy

MCP_AUDIT_LOG

audit.log.jsonl

Audit log location

MCP_SANDBOX_DIR

sandbox

The only directory file tools can read

MCP_HOST / MCP_PORT / MCP_PUBLIC_URL

127.0.0.1 / 8000

HTTP bind address and public URL

For production, replace the local token command with your identity provider (Entra ID, Okta, Auth0) and switch JwtTokenVerifier to RS256 with the provider's public keys. The rest of the server does not change.

Tests

pytest -q

The 28 tests cover forged, expired, alg: none and wrong-audience tokens; deny-by-default policy; audit tampering and deletion; path traversal and symlink escapes; and end-to-end calls through a real MCP client over both in-process and streamable HTTP transports.

Project layout

src/secure_mcp_server/
  auth.py      # agent identity: issue and verify JWTs
  policy.py    # least-privilege, deny-by-default tool policy
  audit.py     # hash-chained, redacted audit log + verifier
  tools.py     # tool logic and input validation
  server.py    # Guard: identity -> policy -> tool -> audit, and the MCP server
  __main__.py  # CLI: serve, token, verify-audit

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Local zero-trust permission gateway for AI agents. Enforces policy-based tool authorization, human approvals, scoped permissions, and cryptographically verifiable audit logs.
      4
      128 PyPI
      5
      Apache 2.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to securely discover, execute, and observe tools with role-based access control and audit logging. Serves tools over MCP stdio and HTTP for integration with Claude Desktop, Cursor, and other clients.
      1
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables secure exposure of internal tools to LLM clients with API-key authentication, tenant isolation, per-tool guardrails, PII scrubbing, rate limiting, audit logging, and telemetry over stdio and HTTP/SSE.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables developers to expose product operations as model-callable tools over stdio or Streamable HTTP with bearer-token auth, per-client rate limits, host allow-listing, structured call logging, and a swappable backend for secure, testable deployments.
      3
      MIT