# @promptjang/mcp-server

Official local MCP server for PromptJang. It exposes bounded delivery and mailbox tools over stdio.

- Targets and delivery: `list_targets`, `send_event`, `get_event`, `replay_event`, `get_usage`
- Agent mailbox: `list_mailboxes`, `list_unread`, `get_message`, `claim_message`, `ack_message`

The server never accepts a destination URL. `send_event` requires a registered target ID returned by `list_targets`.

MCP-originated items follow the same usage contract as the application API. Each newly accepted webhook event, mailbox message, or A2A handoff creates one usage record at the published $0.10 per 1,000 accepted-item rate. Retries, reads, claims, acknowledgements, replays, rejected requests, and idempotent duplicates create no additional usage. Live billing is disabled during the founder-assisted beta, so these records are not currently exported to Stripe or charged.

Mailbox consumers follow one bounded lifecycle: list unread messages, claim one for a five-minute lease, process it, then acknowledge it with the same API key.

## Run

Requires Node.js 20 or later and a PromptJang API key.

```bash
export PROMPTJANG_API_KEY=pj_live_your_key
npx --yes github:PromptJang/promptjang-mcp
```

The source repository is the supported install path for v0.1.1. The
`@promptjang/mcp-server` npm registry package is not published yet.

## Codex

```toml
[mcp_servers.promptjang]
command = "npx"
args = ["-y", "github:PromptJang/promptjang-mcp"]

[mcp_servers.promptjang.env]
PROMPTJANG_API_KEY = "pj_live_your_key"
```

## Claude Code

```bash
claude mcp add promptjang --env PROMPTJANG_API_KEY=pj_live_your_key -- npx -y github:PromptJang/promptjang-mcp
```

Keep the API key in an environment or secret manager. Do not commit it to a project configuration.