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

Built by Lanier, an applied AI studio. More free tools at lanierdev.com/tools.