Penny MCP integration reference

Keep one set of memories and notes across the AI tools you use. Penny provides searchable notes, profile context, tasks, trackers, projects, and saved skills through the Model Context Protocol (MCP).

This reference is public. Reading the documentation, initializing the connection, and listing tools do not require an account. Reading or changing a user's data requires that user's authorization and an account with access to Penny.

Connection and discovery

Use an MCP client for an authenticated connection. The endpoint accepts JSON-RPC requests over HTTP POST. A plain browser GET to /mcp is not a tool call. The examples below use protocol revision 2025-03-26, which the server supports. Use the revision returned by initialize for subsequent requests.

Send Content-Type: application/json and Accept: application/json, text/event-stream. Send the negotiated version in MCP-Protocol-Version. These examples return JSON. Penny does not expose a GET event stream at this endpoint. If initialization returns an Mcp-Session-Id header, preserve it on subsequent requests.

The downloadable catalog is generated from the server's advertised tools at build time. The connected server's tools/list response is authoritative if the server has changed since the documentation was built. It is an MCP catalog, describing the tools and their arguments.

Try discovery without signing in

Initialize the connection:

curl https://app.mypenny.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-03-26' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-mcp-client","version":"1.0"}}}'

A successful response has a result containing protocolVersion, capabilities, serverInfo, and operating instructions. For example, the protocol revision appears at result.protocolVersion; the catalog version appears at result.serverInfo.version.

List the tools and their input schemas:

curl https://app.mypenny.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-03-26' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

The response is a JSON-RPC result with a tools array. Each tool has a name, description, and JSON inputSchema. A successful discovery request confirms the endpoint is reachable; it does not establish access to anyone's memory.

Authorization and first use

1. Create a Penny account, or use an existing account. Verify your email address if prompted.
2. Add the remote MCP endpoint to your client. Follow the client-specific installation guide.
3. Let the client discover the protected-resource metadata and the authorization server it names. Penny supports OAuth authorization code flow, dynamic client registration, and PKCE S256. Compatible clients do not need a manually supplied client secret.
4. Complete sign-in and approve the connection in the browser. Account creation and consent belong to the user; an assistant can guide the setup.
5. Send the resulting access token in the Authorization: Bearer … header for tool calls. Let the client's OAuth implementation handle token refresh.
6. After initialization, send the notifications/initialized notification without a JSON-RPC id. The server acknowledges it with HTTP 202.
7. Call penny_session_start and follow its pennySkill guidance. If meta.onboarded is false, offer the setup conversation through penny_start_setup. Then make a small read such as the tags example below. An empty list is a valid result for a new account.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "penny_read",
    "arguments": { "target": "tags", "view": "list" }
  }
}

Send this body to the same endpoint with the bearer token and the negotiated protocol version. Tool results use MCP's content array. Text entries may contain JSON; decode the text when the tool describes a JSON result. Check isError before treating a result as successful. Tools do not currently advertise output JSON schemas, so clients should not assume every tool returns the same object shape.

Disconnect a client in Settings > Connections. Revocation blocks later authenticated calls from that installation. Reconnecting uses a new authorization flow.

Tool reference

Use the generated catalog for complete arguments, enum values, descriptions, and annotations. Check the current tool schema before constructing a call; different target and entityType values have different required fields.

For example, search notes with:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "penny_read",
    "arguments": {
      "target": "search",
      "query": "What did we decide about the launch?",
      "limit": 5
    }
  }
}

Search results describe what matched and the scope it came from. A result from a shared Space is information supplied by a member of that Space; it is not automatically a fact about the current user.

Reading the profile on a schedule

A client that reads the profile repeatedly, such as a coding-tool hook or an automation, can skip the transfer when nothing has changed. Every profile read (penny_read with target: "profile") returns a revision. Store it with your copy of the profile and send it back as ifRevision on the next read:

{
  "target": "profile",
  "blockNames": ["persona", "user_facts"],
  "ifRevision": "r1.5f0c…"
}

If nothing you would see has changed, the result is { "unchanged": true, "revision": "…", "meta": { "saveDrought": false } }, and the copy you hold is current. Otherwise you get the full profile with a new revision.

A revision belongs to one user and one request shape (the workspace, project, and block names you asked for), so keep one per shape. Treat it as opaque. An unrecognized or outdated value returns the full profile rather than an error. An unchanged answer decrypts nothing, so it adds no entry to the user's access record. It still counts toward the read rate limit below.

Errors and recovery

Check both the HTTP status and the MCP result. Protocol errors use a JSON-RPC error object; a tool can return HTTP 200 with isError: true and an explanation in content. HTTP boundary rejections can instead return a JSON object with error, message, and correlationId.

A typical unauthenticated tool call returns HTTP 401 with a body shaped like:

{
  "error": "unauthorized",
  "message": "Authentication is required.",
  "correlationId": "request-specific-id"
}

Share the correlation ID and the failing method with support@mypenny.ai when reporting a problem. Keep access tokens and note contents out of support diagnostics.

Pricing and request limits

Penny offers a 14-day free trial. No card is needed to start. The standard Penny plan is $99 / year. Penny Founding Member is $59 / year, subject to availability, with the founding price locked for life. These are annual subscriptions. See the public pricing information and the terms shown at checkout.

Default MCP rate limits are 60 read calls per minute and 30 write calls per minute per user. Account-specific overrides may apply. These limits control request throughput independently of note storage and subscription pricing. Use the server's rate-limit response to decide when to retry. MCP request bodies are limited to 2,000,000 bytes; requests above that limit receive HTTP 413.

Data model, portability, and retention

• Notes contain text and metadata such as tags, timestamps, source, and confidence. Search combines meaning and keywords.
• Profile blocks hold the context the assistant needs across conversations.
• Tasks and projects track work and its state. Project edits use revision checks; read the current project before submitting a revision.
• Trackers define measurements and their entries. Saved skills hold reusable instructions and run history.
• Private memory and shared Spaces have separate access boundaries. Choose the intended scope explicitly for operations that support it.

Download an export in Settings > Privacy, or request one through privacy@mypenny.ai. Penny's export formats include JSON for a reimportable bundle, Markdown ZIP for notes and profile blocks, and CSV ZIP for trackers. The formats serve different purposes; Markdown and CSV are not substitutes for the full JSON bundle.

Notes and other supported items moved to Trash can be restored during the 30-day recovery period. A scheduled purge removes expired Trash items. Moving an item to Trash is distinct from requesting account deletion. Some accountability records remain after account deletion. A Trash purge does not promise immediate removal from retained backups. See the Privacy & Security policy for account deletion, raw-input retention, and the service's data-handling terms.

Penny receives explicit tool calls and the data the connected client sends. It does not read a host's hidden chat history or uploaded files through this connector. Content is encrypted in storage using AES-256-GCM and transported over HTTPS. Authorized AI tools receive the memory they request in plain text. We don't train on your data, and we only use AI providers that don't train on it either. See how Penny works for the security design and transparency information for access records.

Support and compatibility

• Installation guides
• Public product overview and pricing
• Privacy & Security
• Terms
• Support

Record serverInfo.version from initialize when diagnosing a compatibility problem. Refresh tools/list after a catalog change. Documentation availability and a successful initialization are not a guarantee that every authenticated operation is available for a particular account.