# Permissioned MCP Server

[![CI](https://github.com/sn0bored/permissioned-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/sn0bored/permissioned-mcp-server/actions/workflows/ci.yml)

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.

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

Example client configuration:

```json
{
  "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](docs/DECISIONS.md) for the reasoning behind discovery filtering, double authorization, confirmation design, audit redaction, transport choice, and storage isolation.

## Verify it

```bash
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](https://lanierdev.com), an applied AI studio. More free
tools at [lanierdev.com/tools](https://lanierdev.com/tools).