Permissioned MCP Server

A compact Model Context Protocol server that demonstrates the parts usually missing from quickstarts: explicit tool boundaries, least-privilege discovery, execution-time authorization, destructive-action confirmation, and metadata-only audit logs.

The domain is deliberately boring: a local note store. The reference is about designing a safe boundary between an AI agent and real side effects.

What it demonstrates

• JavaScript on Node.js with the official MCP SDK v2
• Narrow read, write, and destructive tools
• Separate notes:read, notes:write, and notes:admin scopes
• Unauthorized tools omitted from tools/list and rejected again at execution
• Identifier-bound confirmation for destructive actions
• Structured tool results and MCP behavior annotations
• Audit events that never log arguments, content, or credentials
• Atomic local persistence with restrictive file permissions
• Tests for policy, handlers, persistence, and failure cases

Run it

Requires Node.js twenty or newer.

npm install
cp .env.example .env
MCP_SCOPES=notes:read,notes:write npm start

Example client configuration:

{
  "mcpServers": {
    "permissioned-notes": {
      "command": "node",
      "args": ["/absolute/path/to/permissioned-mcp-server/src/server.js"],
      "env": {
        "MCP_SCOPES": "notes:read,notes:write",
        "MCP_DATA_FILE": "/absolute/path/to/notes.json",
        "MCP_ACTOR": "local-agent"
      }
    }
  }
}

Start read-only. Grant notes:write only when mutation is necessary. Keep notes:admin out of the default configuration.

Tool boundary

Tool	Scope	Side effect
notes.list	notes:read	Returns metadata only
notes.get	notes:read	Reads one note
notes.create	notes:write	Creates one note
notes.delete	notes:admin	Permanently deletes one note

See the decision record for the reasoning behind discovery filtering, double authorization, confirmation design, audit redaction, transport choice, and storage isolation.

Verify it

npm run check
npm test

The test suite never starts a model or calls a paid API.

Production notes

This is a local stdio reference, not a turnkey hosted authorization server. Before exposing an MCP server over Streamable HTTP, add OAuth-based authorization, token audience validation, HTTPS, rate limits, tenant isolation, durable audit storage, and client-specific consent.

License

MIT