Skip to content

MCP and API reference

Use MCP for agent access. Use the signed-in workspace for owner management. Both enforce the account and project boundary.

https://memford.ai/mcp

Memford provides Streamable HTTP MCP with OAuth or a project-bound Bearer key. Use your client’s supported credential storage; never embed credentials in a prompt or URL. OAuth supports public-client registration, PKCE S256, rotating refresh tokens and revocation. Native client discovery uses:

/.well-known/oauth-protected-resource/mcp
/.well-known/oauth-authorization-server

Connect agents covers login, project selection, renewal and reconnecting. The server offers HTTP protocol versions 2025-11-25, 2025-06-18 and 2025-03-26. Use an MCP client library to negotiate the protocol and manage transport sessions.

Every project read includes a compact capabilities hint: product revision, memory_features tool name, a public guide URL and a refresh reminder. The central guide contains current product capabilities and the working method for project context, skills and authorized outcomes. It contains no account data and grants no permissions.

Compare the hint with the last guide revision successfully loaded in the current session. When unknown or changed, call memory_features or retrieve the public feature and working guide, then confirm the returned revision matches. Reuse that guidance while the revision stays the same. Do not mark a hint as successfully loaded or save changing guidance over local user instructions. On failed retrieval or a revision mismatch, report the limitation and retry on the next relevant read; older guidance is not confirmed current.

The reminder travels with ordinary reads, including in an existing MCP session. No new tool or repeated setup is needed to fetch the guide. This is discovery on the next read, not a background push or guaranteed client execution. Newly added tools may still require the client’s supported tool refresh or reconnect. Disconnected clients, or clients that never read or expose the response, cannot receive the update.

Tool Arguments Result
memory_features No arguments Versioned product capabilities, central working guidance and client limitations.
memory_list_skills Optional project_id Active assigned skill metadata and assignment revision; no full procedure content.
memory_get_skill skill_id; optional project_id Current full active assigned skill with its exact revision and owner provenance.
memory_list_projects Optional limit and offset The project authorized by this connection, its metadata and retained original-note count; next_offset when applicable.
memory_read project_id; optional limit, cursor and compact Project metadata, active current notes, active assigned standards, memory_revision, standards_revision, separate approved_context and next_cursor.
memory_write project_id, content; optional source, checkpoint_id and expected_memory_revision A retained original note with its ID, exact content, authenticated writer and context_version_check.

For the two skill tools, omitting project_id uses the authenticated connection’s project. An explicit ID cannot expand access. MCP initialization includes this project ID and the active assigned skill catalog as metadata; fetch the selected current procedure before applying it. No local skill installation is required.

limit is 1–100 and defaults to 100. Notes are paged from the newest submissions toward older ones, but each returned page lists its notes oldest first. Pass next_cursor unchanged to memory_read until it is null. The cursor is opaque, not a timestamp to construct yourself.

Use compact: true to receive the latest owner-approved consolidated context plus active notes that it does not cover. The default (false) still returns original current notes. Compact context retains source IDs and exact revision references, while verbatim evidence quotes remain available in the workspace review and original-note reads. Standards remain separate and complete in both modes. A compact page may contain no uncovered notes and still have next_cursor; follow that cursor to reach older uncovered notes.

New incremental drafts provide source_count and a bounded source-reference page with sources_next_offset. Owner API consumers can follow the source endpoint with offset and limit (up to 100). Draft state includes saved processing progress; a generating response is not a completed draft. Reading progress never starts a model request.

For incremental compact reads, originals whose complete text is not covered by the final evidence remain in the returned note pages. This conservative rule can limit compression; a processed source is not automatically safe to omit.

Editing, deactivating or deleting any snapshot source invalidates the approved context. New notes remain separate until a later draft is reviewed. Draft generation requires explicit consent; optional project automation creates review drafts after new notes, at most once per hour and subject to shared usage limits. It never approves or publishes a draft automatically. Approval advances the project change revision so supporting subscribers receive the existing change hint and can fetch the new context. Clients still control when retrieved context enters their session.

Assigned skill metadata and skills_revision repeat on reads; retrieve full content only when needed. See Skill library.

Active standards repeat in full on every note page with their exact revisions. A read does not merge them into original notes. project.notes_count counts retained submissions, including inactive or deleted notes, so it can differ from the active notes returned. Pagination retrieves stored notes; it is not semantic search.

Results include structured content and a JSON text representation. A tool result with isError: true is a failed operation even if the HTTP transport succeeded. Check the returned project ID before using the contents.

Pass a verified project ID and selected knowledge, for example:

{
"project_id": "<verified-project-id>",
"content": "Decision: use TypeScript for shared modules.",
"source": "Engineering session",
"expected_memory_revision": 42
}

content must be nonblank and can contain up to 32,000 characters. source is an optional label of up to 120 characters. It is not verified identity: the server records the actual authorized connection and account separately. The complete HTTP JSON request is limited to 64 KiB; non-ASCII text and JSON escaping also consume bytes.

Use the memory_revision of the context actually used to derive the contribution; 42 above is only an example. For a protected write, expected_memory_revision must be a nonnegative safe integer. Its comparison and the append happen atomically. Notes, assigned rules, skill changes, project metadata and human-approved context advance the project revision. A successful original receipt includes context_version_check with status: "checked", expected_memory_revision and committed_memory_revision.

A stale basis returns isError: true with structuredContent.error.code: "memory_revision_conflict" and the expected/current revisions. Read current context and reassess the proposed contribution before submitting a new checkpoint. Do not automatically replace the expected revision or resubmit the same conclusion without review. This check protects the Memford append; it does not fence external file changes or tool actions unless their host implements that path.

Existing clients may omit the version and continue writing. Their receipts explicitly report status: "unverified"; old notes are not retroactively certified. A checked receipt describes the original append, not a later owner edit or proof that the model understood the context.

After writing, read the note back and match its ID and exact text. Follow older pages when needed. A write receipt alone does not prove that the note is still active or has reached another agent’s working context.

For a write that may need retrying, generate a lowercase UUID checkpoint_id before the first request. Retain that ID with the exact content, source and expected revision (including its absence for a legacy write).

An identical retry by the same authorized writer in the same project returns the original receipt without another note, even if the project has advanced since a lost success response. Different content, source or expected revision with that ID is rejected. A different connection is a different writer, even when it uses the same ID.

Retrying never reverses an owner’s later edit, deactivation or deletion. The receipt still describes the original submission; read the current active state before reporting recovery. Use a new ID only for genuinely new knowledge. The terminal adapter manages these selected checkpoints and exact readback.

The active project resource has this URI:

memory://projects/<verified-project-id>/notes

It returns the same active context as memory_read, with at most 100 notes and a cursor for older pages. Standards remain complete. A supporting client can:

  1. Initialize MCP and retain its Mcp-Session-Id.
  2. Subscribe using resources/subscribe for that exact URI.
  3. Keep the authenticated HTTP GET event stream open.
  4. After subscribing, reconcile current context even if no hint arrived. On notifications/resources/updated, read again. Use memory_read to follow older pages and restart reconciliation if their revisions differ.
  5. Provide the fetched context at the next supported model boundary. Coalesce duplicate hints and repeat reconciliation after interruption, stream end, missing session or restart.

Changes are checked approximately every five seconds. The stream closes after approximately 55 seconds and the client reconnects. Reattachment can repeat a change hint so the client fetches the latest state after a missed connection; hints are not a replay of every intermediate event or the full note content.

Retained transport sessions expire after one hour of inactivity. Reinitialize a missing session and resubscribe. This is separate from OAuth expiry and usually does not need another browser login. Terminate an unused session with authenticated HTTP DELETE. Authorization and revocation are checked again on open streams.

Record receipt, completed loading and provision to the next model call separately. None proves model understanding or compliance. Streamable HTTP support alone does not establish subscription or host integration. Clients without a verified stream path use supported boundary hooks or ordinary reads; stateless legacy tool POSTs remain available.

This endpoint implements the 2025 transport generation. The 2026-07-28 transport uses a different subscription mechanism and is not advertised by this endpoint. Do not mix its subscriptions/listen contract with this GET/session path.

Situation Next action
HTTP 401, invalid or expired authentication Let an OAuth-capable client refresh stored authorization. If revoked or beyond its renewal limit, reconnect and approve the intended project. For a key, check its scope and revocation in the workspace.
HTTP 404, missing MCP session Initialize a new transport session and resubscribe.
Wrong or unavailable project Verify the selected ID and account. Do not create a duplicate to work around denied access.
Memory changed during a read Retry the read; do not combine a new revision with stale content.
memory_revision_conflict on write Read current context, reassess the contribution and explicitly stage a new reviewed checkpoint. Keep the rejected checkpoint intact.
Checkpoint conflict Preserve the original ID and payload. Investigate the mismatch instead of repeatedly regenerating IDs.
HTTP 429 Respect the server’s retry delay. Do not spin in a request loop.
Interrupted write or readback Keep the selected checkpoint pending. Report saving as unverified until exact readback succeeds.

The /api/ routes require the owner’s browser session. MCP tokens cannot call them to edit notes, manage standards or mint credentials. Mutations require the service origin. Do not export a browser session to an agent; use MCP for agent operations.

Area Routes
Workspace identity and sign-out GET/PATCH /api/me; POST /api/logout
Projects GET/POST /api/projects; GET/PATCH/DELETE /api/projects/:id
Current notes and original submissions GET/POST /api/projects/:id/notes; GET/PATCH /api/projects/:id/notes/:noteId
Retained note revisions GET /api/projects/:id/notes/:noteId/revisions
Standards GET/POST /api/standards; GET/PATCH /api/standards/:id; GET /api/standards/:id/revisions
Project standard assignments GET/PUT /api/projects/:id/standards
Skill starter templates GET /api/skill-templates
Skills and retained revisions GET/POST /api/skills; GET/PATCH /api/skills/:id; GET /api/skills/:id/revisions
Project skill assignments GET/PUT /api/projects/:id/skills
AI review state and automatic draft settings GET /api/projects/:id/consolidation; PUT /api/projects/:id/consolidation/settings
Queue a complete-project review draft POST /api/projects/:id/consolidation/drafts
Page through draft source references GET /api/projects/:id/consolidation/drafts/:draftId/sources
Approve or reject a draft POST /api/projects/:id/consolidation/drafts/:draftId/review
Project keys GET/POST /api/tokens; DELETE /api/tokens/:id
OAuth connections GET /api/connections; DELETE /api/connections/:id

Note, standard and skill updates require expected_revision. Project assignments require their own assignment revision and standard_ids or skill_ids. Stale updates fail with a conflict. Owner note lists include retained inactive/deleted notes and original contents; agent reads include active current notes only. Notes and history, Shared standards and Skill library explain those controls.

Automatic draft settings require enabled and expected_revision; enabling them also requires consent: true. Manual draft generation requires consent: true. Draft review takes decision: "approve" or decision: "reject" and accepts only a draft awaiting review. Approval also checks that its covered source notes still match. These are owner actions; project-scoped MCP credentials cannot perform them. See AI review for processing consent, limits and the required human decision.

Profile updates accept name and the current expected_revision from user.profile_revision. Project metadata updates accept name, description, group_name and expected_revision from project.metadata_revision. A stale revision returns HTTP 409 for explicit reconciliation. These owner-session operations keep project identifiers and existing agent grants unchanged. Email and authentication identifiers cannot be changed through these endpoints.