MutualsMutuals

Connect an agent

Last updated 18 October 2026

Mutuals is a relationship memory your agents share. It speaks the Model Context Protocol, so any agent that supports remote MCP servers with OAuth can read and write to it with your permission.

Endpoint

https://app.getmutuals.ai/mcp
  • Transport: Streamable HTTP.
  • Sign-in: OAuth 2.1 authorization code with PKCE (S256). Clients register themselves through dynamic client registration, so there is no API key to copy and nothing to paste into a config file.
  • Discovery: /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/mcp on the same host.

Any Google account can sign in. The first sign-in, including one that starts from an agent's connection screen, creates a new and empty workspace for that account, so there is nothing to set up beforehand.

Setup

Add the endpoint, then finish sign-in in the browser window your agent opens.

Claude Code

claude mcp add --scope user --transport http mutuals https://app.getmutuals.ai/mcp
claude mcp login mutuals

Codex

codex mcp add mutuals --url https://app.getmutuals.ai/mcp

Hermes

hermes mcp add mutuals --url https://app.getmutuals.ai/mcp --auth oauth

Any other agent

Look for "add custom connector" or "remote MCP server" in its settings and paste the endpoint. If it supports OAuth with dynamic client registration, the rest is the same browser sign-in.

A new workspace starts empty, so save something before you search. Try it with a fictional person: "Remember that Maya Testbrook enjoys sailing." followed by "What do I know about Maya Testbrook?"

What we have tested

We only list a client as working after running its real, installed version against Mutuals.

  • Claude Code 2.1.278: sign-in, consent and tool discovery.
  • Codex 0.154.0: sign-in, consent, save, recall with sources, and undo.
  • Hermes Agent 0.21.3: sign-in, consent and tool discovery.
  • Muse: our connector is in Meta's review. Grok: not verified yet. Neither is listed as supported until it has been run end to end.

Permissions

The consent screen shows exactly what the agent is asking for. Reading is always disclosed. Writing is optional and starts unchecked.

  • relationships:read lets the agent search people and read one person's context.
  • relationships:remember lets it save, resolve and undo notes.
  • followups:write lets a saved note create follow-ups. It is asked for separately.

Each connection is tied to one person and one workspace. An agent never sees another user's data.

Tools

Six tools. Each carries MCP annotations, so an agent can tell reads from writes before it calls one. None is a sensitive write: no tool pays, sends a message, shares data, changes who has access, or deletes anything it did not create.

search_relationships · relationships:read · Read

Search people and notes

Keyword search over saved people and dated note excerpts. Results are candidates, not answers.

  • Input: q, 3 to 300 characters; limit, 1 to 20 (default 10).
  • Output: Matching people with a snippet, dated evidence excerpts, and whether the list was cut off.
  • Side effects: None. Nothing is stored and no language model is called.

get_person_context · relationships:read · Read

Get a person’s context

Current fields, recent source notes and open follow-ups for one exact person.

  • Input: id, the person’s ID from a search result.
  • Output: The person, their current fields, recent dated notes, open follow-ups and a link to the profile.
  • Side effects: None.

get_capture · relationships:read · Read

Check a saved note

The status of a note this connection saved. Safe to poll after an interruption.

  • Input: id, the note workflow ID that remember returned.
  • Output: The workflow’s status, any open questions, and what was saved.
  • Side effects: None. No language model is called.

remember · relationships:remember · Write, not sensitive

Remember a note

Save a note you asked Mutuals to remember, in your wording. It either saves or comes back with a question.

  • Input: text, the note, up to the capture limit; idempotencyKey, 8 to 128 characters, reused for every retry; includeFollowUps, which also needs followups:write.
  • Output: A note workflow: its status, the questions to answer if any, and what was saved.
  • Side effects: Adds the note to the people it names, creating a person only when nobody matches, and with followups:write a follow-up. One language-model call, counted against the daily budget. Nothing is sent to anyone.

resolve_capture · relationships:remember · Write, not sensitive

Answer a question about a note

Apply your answer to a pending question, for example which of two Mayas you meant.

  • Input: id and revision of the workflow; action, one of choose, confirm or cancel; mentionId and optionId for a choice.
  • Output: The updated note workflow.
  • Side effects: Saves the pending note with your answer, or discards it on cancel. A stale revision is refused rather than applied.

undo_capture · relationships:remember · Write, not sensitive

Undo a saved note

Undo a note saved through this same connection. It refuses if later edits would be lost.

  • Input: id of a note workflow this connection saved.
  • Output: The note workflow, now undone.
  • Side effects: Reverts what that one note changed. People it created stay. It cannot touch anything else, and it is marked destructive so an agent asks first.

No tool can message your contacts, delete your account or export your whole database.

Statuses and errors

A note moves through one of these statuses. Only saved, cancelled, undone and failed are final.

  • processing: still being read. Poll get_capture.
  • needs_clarification: Mutuals needs to know which person a name means, or the note names nobody. The message says which; ask the user, then call resolve_capture or cancel.
  • needs_confirmation: a detail that would change a profile was uncertain and needs the user's explicit yes.
  • saved, cancelled, undone, failed: done; the message says what happened.

Errors come back as a tool error with a sentence the agent can act on:

  • 401: access expired or was revoked. Reconnect.
  • 403: this connection was not granted the permission the tool needs.
  • 404: no such person or note in this connection's workspace.
  • 409: the note changed, or an idempotency key was reused for a different note. Read its status before retrying.
  • 429: rate limit or daily budget. Retry later with the same idempotency key.
  • An interrupted write may have completed. Poll get_capture or retry the original key; never create a new one.

Limits and behaviour

  • 120 requests per minute per connection. Beyond that the server answers 429 and asks the agent to wait a minute.
  • Saving a note uses a language model, and each workspace has a daily model budget. When it is used up, saves are refused until the next day. Reading keeps working.
  • Every save carries an idempotency key. A retry of the same note reuses its key, so an interrupted request never saves twice.
  • If a name matches more than one person, Mutuals asks which one. It does not guess.
  • Saved notes are data. If a note contains instructions, agents are told to treat them as text, not as commands.

Disconnect

Open Mutuals, then Settings, then Connections, and disconnect the agent. Its future requests fail immediately. This does not recall anything the agent already received, which is governed by that agent's own privacy terms.

Help

Write to hello@getmutuals.ai. See also our privacy policy and terms.