@permitplane/mcp
v0.1.0
Published
MCP server that lets AI assistants operate PermitPlane through the management API (/manage/v1).
Maintainers
Readme
@permitplane/mcp
MCP server that lets AI assistants (Claude, Cursor, Codex) operate PermitPlane through the management API
(/manage/v1). It is a thin translator: which tools exist, their schemas, descriptions, prompts and server
instructions all come from the PermitPlane server you point it at (GET /manage/v1/agent/tools), so the tools always
match that server's version. It runs over stdio.
Install
npx -y @permitplane/[email protected]Licensed under Apache-2.0. Homepage: https://permitplane.com
Requirements
Node.js 22 or newer.
Configuration
| Setting | Environment variable | Config file field | Notes |
| --- | --- | --- | --- |
| API key | PERMITPLANE_API_KEY | api_key | Optional. Without a key only public tools (docs, agent signup) are available. |
| Base URL | PERMITPLANE_BASE_URL | base_url | Required. https:// only, except http://localhost, 127.0.0.1, [::1]. No default origin. |
| Config file path | PERMITPLANE_CONFIG | - | Overrides the default path below. |
Precedence: the environment variable, then the config file.
Default config file: %APPDATA%\PermitPlane\mcp.json on Windows, $XDG_CONFIG_HOME/permitplane/mcp.json or
~/.config/permitplane/mcp.json elsewhere. Format:
{ "base_url": "https://<your PermitPlane origin>", "api_key": "ppk_test_..." }On macOS and Linux run chmod 600 on the file; the server warns on stderr when it is readable by others.
No tool takes an API key as an argument, and the key is never logged.
Public mode and signup
Without a key the assistant can read the public docs and start an agent signup. A human confirms by email. When the signup completes, the server saves the new key to the config file (only when no key was configured), switches to the full tool set and tells the client the tool list changed. The key is not shown in the conversation. If your client does not refresh its tools, restart the server.
Client setup
Recommended: keep the key and base URL in the PermitPlane config file, so client configs hold no secret.
Claude Desktop, claude_desktop_config.json (Windows %APPDATA%\Claude\, macOS ~/Library/Application Support/Claude/):
{
"mcpServers": {
"permitplane": {
"command": "npx",
"args": ["-y", "@permitplane/[email protected]"]
}
}
}Alternative with environment variables (the key then sits in this local file):
{
"mcpServers": {
"permitplane": {
"command": "npx",
"args": ["-y", "@permitplane/[email protected]"],
"env": { "PERMITPLANE_BASE_URL": "https://<your PermitPlane origin>", "PERMITPLANE_API_KEY": "ppk_test_..." }
}
}
}Claude Code (user scope; the key stays in the PermitPlane config file):
claude mcp add --scope user --transport stdio permitplane -- npx -y @permitplane/[email protected]Shared project config .mcp.json (commit it; each developer's key comes from their own environment through ${VAR}
expansion, never from the repository):
{
"mcpServers": {
"permitplane": {
"command": "npx",
"args": ["-y", "@permitplane/[email protected]"],
"env": { "PERMITPLANE_BASE_URL": "https://<your PermitPlane origin>", "PERMITPLANE_API_KEY": "${PERMITPLANE_API_KEY}" }
}
}
}Cursor, ~/.cursor/mcp.json (global) or .cursor/mcp.json (project): same mcpServers shape as Claude Desktop.
Codex, ~/.codex/config.toml:
[mcp_servers.permitplane]
command = "npx"
args = ["-y", "@permitplane/[email protected]"]Behaviour
| Server answer | What the assistant sees |
| --- | --- |
| 2xx JSON | The JSON, labelled as data; a "store now" note when a secret field is present (shown once). |
| 2xx other (CSV, Markdown, ...) | The raw text, cut at 100 000 characters. |
| 200 preview (dry_run=true) | "Preview only", the effects, whether approval is needed. The preview token is kept by the server process. |
| 202 approval_required | Success, not an error: the console link a human owner opens, the request id, the expiry. |
| 4xx | Error with code, hint, docs slug (permitplane://docs/<slug>), field errors and request_id. 401 points at the config file. |
| 429, 502, 503, 504, connection failure | Up to 2 retries when safe (GET, or a mutation with an Idempotency-Key), then an error. |
| Redirects | Refused. |
Every mutation carries an Idempotency-Key. A destructive tool is refused locally until the same call was previewed
with dry_run=true in this session (10 minutes). The preview token is then sent with the real call.
Security notes
- The key is never a tool argument, never logged, never written to stdout. stdout carries JSON-RPC only.
- The base URL must be https (loopback excepted). Tool paths from the server must start with a single
/and are always prefixed with the base URL; redirects are refused. - Tool results are labelled as data from PermitPlane, not instructions.
- Runtime dependency: one package,
@modelcontextprotocol/server, pinned exactly;npm-shrinkwrap.jsonpins the rest.
Troubleshooting
- 401: the key expired, was revoked or belongs to another server. Create a new key in the console and put it in the config file.
- Tools did not refresh after signup: restart the PermitPlane MCP server in your client.
- Windows, the client cannot start
npx: use"command": "cmd", "args": ["/c", "npx", "-y", "@permitplane/[email protected]"].
