MCP and API reference

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

Endpoint and authentication

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.

Tools

Tool	Arguments	Result
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 and cursor	Project metadata, active current notes, active assigned standards, memory_revision, standards_revision and next_cursor.
memory_write	project_id, content; optional source and checkpoint_id	A retained original note with its ID, exact content, receipt time and authenticated writer.

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.

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.

Write and confirm

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"
}

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.

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.

Retry checkpoints safely

For a write that may need retrying, generate a lowercase UUID checkpoint_id before the first request. Retain that ID with the exact content and source.

An identical retry by the same authorized writer in the same project returns the original receipt without another note. Different content or source 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.

Subscribe to changes

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. On notifications/resources/updated, read the resource again. Use memory_read to follow older pages.

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.

Receiving a hint does not make every agent use it automatically. Clients without subscription support fetch the latest context on their next read.

Handle errors

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.
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.

Owner workspace API

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 /api/me; POST /api/logout
Projects	GET/POST /api/projects; GET/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 assignments	GET/PUT /api/projects/:id/standards
Project keys	GET/POST /api/tokens; DELETE /api/tokens/:id
OAuth connections	GET /api/connections; DELETE /api/connections/:id

Note and standard updates require expected_revision; project assignment updates require their own assignment revision and standard_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 and Shared standards explain those controls.