About Promise
Promise is an agent-facing MCP server for accessing Promise follow-up memory, including commitments, evidence, and notes. It proxies requests to the Promise platform API and directs actions such as resolving items or drafting follow-ups to Promise for user review.
Key features
- 01List and retrieve commitments
- 02View commitment evidence and person context
- 03Search memory and capture notes
- 04Create follow-ups and mark items resolved
- 05Draft follow-ups for review in Promise
Use cases
- 01Review commitments due today
- 02Find evidence for a commitment
- 03Record a note in follow-up memory
- 04Prepare a follow-up for user review
MCP support
Provides agent-facing tools over a hosted HTTP MCP endpoint. Protected calls use scoped bearer tokens, and unauthenticated results guide users through authorization and connection.
Configuration
Remote servers need no local install. Pick your client, then copy the config or install in one click.
https://mcp.usepromise.ai/mcpclaude mcp add --transport http ai-usepromise-promise https://mcp.usepromise.ai/mcp{"mcpServers":{"ai-usepromise-promise":{"type":"http","url":"https://mcp.usepromise.ai/mcp"}}}Open in Cursor{"servers":{"ai-usepromise-promise":{"type":"http","url":"https://mcp.usepromise.ai/mcp"}}}Open in VS Code{"mcpServers":{"ai-usepromise-promise":{"type":"http","url":"https://mcp.usepromise.ai/mcp"}}}{"mcpServers":{"ai-usepromise-promise":{"serverUrl":"https://mcp.usepromise.ai/mcp"}}}Run commands in a terminal; paste JSON into the client’s MCP config and restart. Servers that need sign-in will prompt on first connect.
Tools
11| Parameter | Type | Required | Description |
|---|---|---|---|
| state | string | No | Opaque agent state returned unchanged after authorization. |
| intent | string | No | Signup intent to preserve in Promise attribution. |
| scopes | array | No | |
| returnUrl | string | No | HTTPS URL the user can return to after Promise authorization. |
| clientName | string | No | Name of the agent or MCP client requesting access. |
Details
From the project READMEPromise 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_promiseget_todaylist_commitmentsget_commitmentget_commitment_evidenceget_person_contextsearch_memorycapture_notecreate_follow_upmark_resolveddraft_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.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.