Promise

Official11 tools

by UsePromise · TypeScript

Evidence-backed follow-through memory for what you owe, await, and need to remember.

ai.usepromise/promise is an MCP server described as “Evidence-backed follow-through memory for what you owe, await, and need to remember.” It provides a way to retain memory related to obligations, pending items, and reminders, based on the server’s stated focus on evidence-backed follow-through.

🛠️ Key Features

Evidence-backed follow-through memory
Memory for what you owe, await, and need to remember

🚀 Use Cases

Tracking what you owe
Tracking what you are awaiting
Remembering items you need to keep track of

⚡ Developer Benefits

Clear alignment between the server’s purpose and tracked categories (owe/await/remember)

⚠️ Limitations

Available metadata includes only name and description; no tool list, topics, or usage details are provided.

Captured live from the server via tools/list.

connect_promise

Return a Promise signup URL for users who want agent access to follow-up memory. Safety: Never collects provider credentials in the agent. Send the user to Promise.

Parameters5

clientName	string	optional	Name of the agent or MCP client requesting access.
returnUrl	string	optional	HTTPS URL the user can return to after Promise authorization.
state	string	optional	Opaque agent state returned unchanged after authorization.
intent	string	optional	Signup intent to preserve in Promise attribution.
scopes	array	optional

Raw schema

{
  "type": "object",
  "properties": {
    "clientName": {
      "type": "string",
      "description": "Name of the agent or MCP client requesting access."
    },
    "returnUrl": {
      "type": "string",
      "description": "HTTPS URL the user can return to after Promise authorization."
    },
    "state": {
      "type": "string",
      "description": "Opaque agent state returned unchanged after authorization."
    },
    "intent": {
      "type": "string",
      "description": "Signup intent to preserve in Promise attribution."
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "promise.memory.read",
          "promise.evidence.read",
          "promise.capture.write",
          "promise.followup.write",
          "promise.draft.write"
        ]
      }
    }
  },
  "required": [],
  "additionalProperties": false
}

get_today

Return what currently deserves the user's attention. Safety: Return concise items and links back to Promise for sensitive action.

Parameters1

horizonDays

integer

optional

Raw schema

{
  "type": "object",
  "properties": {
    "horizonDays": {
      "type": "integer",
      "minimum": 0,
      "maximum": 30,
      "default": 7
    }
  },
  "required": [],
  "additionalProperties": false
}

list_commitments

List what the user owes and what the user is waiting on. Safety: Do not infer more certainty than Promise returns.

Parameters3

category	string	optional
scope	string	optional
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "all",
        "waitingOnMe",
        "waitingOnThem",
        "dueSoon",
        "overdue"
      ],
      "default": "all"
    },
    "scope": {
      "type": "string",
      "enum": [
        "active",
        "snoozed",
        "history"
      ],
      "default": "active"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 25
    }
  },
  "required": [],
  "additionalProperties": false
}

get_commitment

Retrieve a structured Promise commitment or waiting-on item. Safety: Prefer structured status, due dates, people, and source links over raw mail.

Parameters1

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

get_commitment_evidence

Show why Promise believes a follow-up or memory exists. Safety: Return source summaries and citations permitted by the platform API.

Parameters1

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

get_person_context

Summarize what matters before the user speaks with someone. Safety: Avoid exposing hidden/private fields unless the platform scopes allow them.

Parameters3

contactId	string	optional
query	string	optional	Name or email search when contactId is unknown.
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "contactId": {
      "type": "string",
      "format": "uuid"
    },
    "query": {
      "type": "string",
      "description": "Name or email search when contactId is unknown."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "default": 5
    }
  },
  "required": [],
  "additionalProperties": false
}

search_memory

Search Promise's derived memory with user authorization. Safety: Search derived Promise memory, not raw provider mailboxes.

Parameters2

query	string	required
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "default": 10
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

capture_note

Let a user tell Promise something to remember. Safety: Echo what Promise understood and require review when the platform requests it.

Parameters7

transcript	string	required
title	string	optional
kind	string	optional
personName	string	optional
contactId	string	optional
dueAt	string	optional
requestId	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "transcript": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "kind": {
      "type": "string",
      "enum": [
        "task",
        "follow_up",
        "remember"
      ],
      "default": "remember"
    },
    "personName": {
      "type": "string"
    },
    "contactId": {
      "type": "string",
      "format": "uuid"
    },
    "dueAt": {
      "type": "string",
      "format": "date-time"
    },
    "requestId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "transcript"
  ],
  "additionalProperties": false
}

create_follow_up

Create a future follow-up from explicit user intent. Safety: Only create follow-ups from explicit user instructions.

Parameters6

title	string	required
transcript	string	optional
personName	string	optional
contactId	string	optional
dueAt	string	optional
requestId	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "transcript": {
      "type": "string"
    },
    "personName": {
      "type": "string"
    },
    "contactId": {
      "type": "string",
      "format": "uuid"
    },
    "dueAt": {
      "type": "string",
      "format": "date-time"
    },
    "requestId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "title"
  ],
  "additionalProperties": false
}

mark_resolved

Tell Promise that a commitment or waiting-on item is complete. Safety: Confirm destructive or irreversible status changes in the agent UI.

Parameters1

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

draft_follow_up

Draft a follow-up message without sending it. Safety: Do not send email in v1. Return a draft and Promise confirmation link.

Parameters4

commitmentId	string	optional
personName	string	optional
context	string	optional
goal	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "commitmentId": {
      "type": "string",
      "format": "uuid"
    },
    "personName": {
      "type": "string"
    },
    "context": {
      "type": "string"
    },
    "goal": {
      "type": "string"
    }
  },
  "required": [],
  "additionalProperties": false
}

README.md2 KBView on GitHub

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

bash

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

Example MCP call:

bash

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.

Install

Tools (11)

connect_promiseget_todaylist_commitmentsget_commitmentget_commitment_evidenceget_person_contextsearch_memorycapture_note

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://mcp.usepromise.ai/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "promise": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.usepromise.ai/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

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

Promise MCP

Boundary

Development

Install

Remote endpoint

Related servers