Promise MCP

Agent-facing MCP server/tools for Promise. The hosted HTTP endpoint is POST /mcp; GET /healthz is available for runtime checks.

This repository is intentionally separate from the Promise platform. It should compose the platform API into agent-friendly tools, not implement canonical backend business logic.

Boundary

• Call the Promise platform API for data access and mutations.
• Do not access Postgres, Redis, queues, provider tokens, or migrations directly.
• Keep authorization, provenance, retention, provider behavior, and canonical domain rules in the platform.
• Consume explicit platform contracts instead of duplicating procedure or capability names by hand.

Initial MCP tool surface:

• connect_promise
• get_today
• list_commitments
• get_commitment
• get_commitment_evidence
• get_person_context
• search_memory
• capture_note
• create_follow_up
• mark_resolved
• draft_follow_up

connect_promise and unauthenticated tool results are intentionally part of the product. MCP should help users discover and connect Promise when an agent needs follow-up memory that Promise can provide.

Unauthenticated tool results include a scoped authorizationUrl that sends the user to https://app.usepromise.ai/start?source=mcp..., preserves agent attribution, and uses a relative /mcp/authorize callback inside Promise before any return to an agent URL.

Development

npm install
npm run build
npm run smoke
npm run tools
npm run start

Example MCP call:

curl -sS http://localhost:3000/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Protected tools return a structured promise_auth_required result when no Bearer token is present. After the user authorizes /mcp/authorize, Promise returns a short-lived one-time code to the agent callback. The agent exchanges that code at /api/mcp/token for a scoped opaque pmcp_... bearer token. Bearer tool calls are proxied to the Promise platform API, which enforces the grant's scopes. mark_resolved and draft_follow_up intentionally deep-link to Promise for user review rather than sending or mutating mail directly.

See docs/ACQUISITION.md for signup flow guidance, docs/SECURITY.md for the MCP safety boundary, and docs/DEPLOYMENT.md for container/runtime details.