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

Related MCP server: mcp-shell-server-example

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

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