@playaos/mcp

Model Context Protocol (MCP) server for PlayaOS — lets AI agents manage camp data via natural language.

Installation

npx -y @playaos/mcp

Or install globally:

npm install -g @playaos/mcp

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "playaos": {
      "command": "npx",
      "args": ["-y", "@playaos/mcp"],
      "env": {
        "PLAYAOS_API_KEY": "your-api-key-here",
        "PLAYAOS_API_URL": "https://your-camp.playaos.app"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | PLAYAOS_API_KEY | Yes | API key from Admin → Settings → Developer | | PLAYAOS_API_URL | Yes | Your camp's PlayaOS URL (e.g. https://wafflecamp.playaos.app) |

Generate API keys at Admin → Settings → Developer (super admins only).

API Key Scopes

Each API key is granted one or more scopes. Tools and resources that require a scope will fail with a clear error if the key lacks it.

| Scope | Tools / Resources | |-------|------------------| | members:read | playaos_list_members, playaos_get_member, playaos://members | | members:write | (reserved for future tools) | | dues:read | playaos_list_dues, playaos://dues | | dues:write | playaos_collect_dues | | applications:read | playaos_list_applications, playaos://applications | | applications:write | playaos_update_application | | shifts:read | playaos_list_shifts | | shifts:write | playaos_signup_shift | | emails:write | playaos_send_email (coming soon) | | org:read | playaos_get_org, playaos://org |

Tools

Read tools

| Tool | Scope | Description | |------|-------|-------------| | playaos_list_members | members:read | List camp members, optionally filtered by role or status | | playaos_get_member | members:read | Get a single member profile by ID | | playaos_list_dues | dues:read | List dues payments and per-member payment status | | playaos_list_applications | applications:read | List applications with optional status/year filters | | playaos_list_shifts | shifts:read | List shifts and signups with optional date/type filters | | playaos_get_org | org:read | Get camp name, slug, plan, and feature flags |

Write tools

| Tool | Scope | Description | |------|-------|-------------| | playaos_update_application | applications:write | Approve, reject, waitlist, or otherwise update an application | | playaos_signup_shift | shifts:write | Sign a member up for a shift | | playaos_collect_dues | dues:write | Look up a member's dues status and return their payment link | | playaos_send_email | emails:write | Send a templated email to one or more members (coming soon) |

Resources

Resources are read-only contextual snapshots AI clients can fetch without a tool call. They give an agent a "what is this camp right now" overview before deciding what to do.

| URI | Scope | Description | |-----|-------|-------------| | playaos://org | org:read | Camp name, slug, plan | | playaos://members | members:read | Member counts by role and status | | playaos://applications | applications:read | Application counts by status and year | | playaos://dues | dues:read | Payment status counts and total balances |

MCP Registry

Published to the official MCP registry as io.github.feeling-mindful/playaos-mcp.

server.json in this directory is the registry manifest. Two invariants the registry enforces, both checked in src/server-json.test.ts:

• mcpName in package.json must equal name in server.json — that pairing is how the registry proves this npm package belongs to this server entry.
• version must match across package.json, server.json, and server.json's package entry.

Publishing a new version to the registry (requires GitHub auth for the io.github.feeling-mindful namespace):

mcp-publisher login github
mcp-publisher publish   # run from packages/mcp

Local development

# From repo root
pnpm --filter @playaos/mcp build
PLAYAOS_API_KEY=pk_live_... PLAYAOS_API_URL=https://your-camp.playaos.app node packages/mcp/dist/cli.js

Publishing

This package is published to npm automatically when a tag matching mcp-v* is pushed:

# Bump version in packages/mcp/package.json, then:
git tag mcp-v0.2.0 && git push origin mcp-v0.2.0

License

MIT