Memoth.ai docs

MCP server

Authentication

Standard OAuth 2.1, exactly as the MCP authorization specification (revision 2026-07-28) lays it out. A person signs in through the browser; a headless agent uses client credentials. Either way the server knows who is asking before it answers.

Signing in from a client

What happens between pasting the URL and the first answer:

  1. The client calls https://mcp.memoth.ai/mcp without a token and gets a 401 whose WWW-Authenticateheader names the server’s protected-resource metadata and the scopes it wants.
  2. From that metadata the client learns the authorization server, https://auth.memoth.ai, and reads its own metadata document.
  3. The client identifies itself: with a Client ID Metadata Document (its client id is an HTTPS URL Memoth fetches), with Dynamic Client Registration, or with a pre-registered id.
  4. Your browser opens at auth.memoth.ai. You enter your work email; Memoth resolves the workspace it belongs to and sends you to that workspace’s sign-in, your company IdP or the Memoth console.
  5. A consent screen names the client, the redirect address it will return to, and the scopes. You approve once per client and scope set; later sign-ins skip the screen.
  6. The client receives an access token bound to https://mcp.memoth.ai/mcp and a refresh token, and every call from then on carries the access token.

The client, not you, handles PKCE, the resource parameter, issuer validation and token refresh. If a client cannot do these it cannot connect, which is the point.

Scopes

Consent scopes
FieldTypeMeaning
memory.read*scopeRead your memory. Unlocks memory_search and whoami. Every connection needs it; a token without it is refused with 403.
memory.writescopeAdd to your memory. Unlocks memory_write. Not needed on the read-only endpoint.
memory.auditscopeReplay your own read receipts. Unlocks memory_receipt.

Scopes only ever narrow. A scope never widens what memory you can see: visibility is decided by your workspace’s access rules and applied to every read, whatever the client asked for.

Step-up. If the client calls a tool its token lacks the scope for, the server answers 403 with error="insufficient_scope" and the scope needed. A spec-conforming client re-authorizes with the wider set; you see the consent screen again with the added item.

Tokens

  • Access tokens live at most 15 minutes. Clients refresh silently.
  • Refresh tokens live up to 30 days and rotate on every use. A rotated-out token that is replayed kills the whole chain, so a leaked refresh token cannot outlive the next legitimate refresh.
  • Every access token is minted for exactly one audience, the MCP server’s URL. It works nowhere else in Memoth, and no other Memoth token works here.

Disconnecting

Remove the server in your client, or revoke from the client with the standard revocation endpoint; both end the refresh chain. A revoked connection stops working within one access token lifetime, at most 15 minutes. Your consent record stays as an audit trail of what was granted and when.

Headless agents

A nightly job or a server-side agent has no browser. It authenticates with the client_credentials grant using a client id and secret bound to your workspace and to a named agent identity.

  1. Create the credential in the console: Identities, the agent’s Keys, the MCP tab, Create MCP credential. An admin does this; the secret is shown exactly once. Connect your own agent covers adding the agent and what it can read.
  2. Exchange the credentials for an access token:
shell
curl -sS https://auth.memoth.ai/v1/token \
  -d grant_type=client_credentials \
  -d client_id=$MEMOTH_CLIENT_ID \
  -d client_secret=$MEMOTH_CLIENT_SECRET
response
{
  "access_token": "eyJhbGciOiJSUzI1NiIs…",
  "token_type": "Bearer",
  "expires_in": 3600
}
  1. Send it as Authorization: Bearer … on every request to https://mcp.memoth.ai/mcp, and fetch a new one before it expires. The id and secret may be posted in the form body, as above, or sent in an HTTP Basic header.

Agents are not people

An agent token carries the agent’s identity, not a person’s. Its reads see what the agent has been granted. Its writes do not land as memory: they are parked as proposals in the workspace’s review queue until a person approves them, and each proposal records which agent made it. memory_receipt is not offered to agents.

Specification compliance

The server follows the MCP authorization specification, revision 2026-07-28: OAuth 2.1 with PKCE (S256 only), Protected Resource Metadata (RFC 9728), Authorization Server Metadata (RFC 8414), resource indicators (RFC 8707) with strict audience checks, issuer identification on authorization responses (RFC 9207), Client ID Metadata Documents, and scope challenges for step-up. Dynamic Client Registration stays available for clients that predate Client ID Metadata Documents.

discovery
https://mcp.memoth.ai/.well-known/oauth-protected-resource/mcp
https://auth.memoth.ai/.well-known/oauth-authorization-server