Configure MCP

Use Configure through MCP clients such as Codex, Claude, and Cursor.

Configure MCP lets an MCP-compatible agent read approved profile context and write attributed memories. For developers, it is an adapter for agents that already use MCP instead of the Configure SDK.

Developer MCP requires a developer API key. Personal MCP does not require a developer API key.

Choose a setup

For myself

Use this when you want Codex, Claude, Cursor, or another MCP client to access your own Configure profile. No developer API key is required.

npx configure setup

Choose For myself, then choose Codex, Claude, Cursor, or another client. The wizard delegates to personal MCP, signs you into your own Configure profile, and prints the exact MCP-server entry to add plus where it goes for the client you picked: ~/.codex/config.toml for Codex, the MCP settings for Claude Desktop or Cursor. See the adapter reference for per-client config snippets.

Direct path:

npx -y @configure-ai/mcp login --personal --client codex

--client takes the client handle (codex, claude, cursor, …); if you skip it, npx configure setup lists the supported clients and picks the value for you.

For Codex, setup updates ~/.codex/config.toml, which is shared by the Codex desktop app, IDE extension, and CLI. Restart the app you use so it reloads config. Desktop and extension users should start a new chat after restart; CLI users can run /mcp to confirm Configure is connected. Writes are attributed to the selected client, for example /agents/codex/.

For my app or agent

Use this when you are building an MCP-compatible agent for other people.

npx configure setup

Choose For my users. Developer setup signs you in as a developer, asks which Configure agent MCP should act as, and connects that agent with an API key.

Remote MCP URL

Use this when a client asks for a hosted MCP server instead of an npx command.

https://mcp.configure.dev

This is the personal MCP endpoint. Remote clients authenticate via OAuth: the client discovers /.well-known/oauth-protected-resource and runs the authorization-code + PKCE flow automatically. There is no token to paste. Developer MCP requires For my users setup with a developer API key.

Connect from ChatGPT or any remote MCP client

1. Paste https://mcp.configure.dev into the client's connector/MCP settings.
2. An OAuth window opens automatically.
3. Complete the sign-in prompt (phone number, then the OAuth confirmation). Done. The client holds server-issued tokens from then on.

If the host discovered the tools but never presented an OAuth window, call the configure_connect tool as the fallback: it returns a connect_url sign-in link that completes the same connection.

The tools

Once connected, the agent sees the user's Configure surface as tools. Before sign-in, the personal tools return an authorization challenge and expose nothing personal; configure_connect mints the sign-in link that fixes that. After sign-in, the remote https://mcp.configure.dev endpoint lists the six profile tools (read, search, remember, forget, commit, import). Connector and action tools are not listed on that surface; they are enforced live, per call. API-key (developer) servers list configure_connect plus the six profile tools, and add the default connector and action tools only when the request carries a linked-user token. Listing is not permission: what actually runs is enforced live, per call. A connector call against an unconnected app fails closed with an error telling you to get the user connected: call configure_connect with that app to mint the link (you never build these links yourself). Only scope and permission failures return a minted permission link directly in the result (permission_needed).

One client caveat: MCP clients cache the tool list when they connect. A tool that appears mid-session (for example after the user connects Notion) shows up on the next fresh connection, not in the session that is already open. New optional parameters behave the same way: the cached schema hides them, but the server accepts them when sent, so patterns learned from these docs keep working on older connections.

Tool	What it does
configure_profile_read	The whole profile in one read: identity, summary, connections, plus a boxes/sources index. Call it once, pre turn. Pass box: "<id>" to open one box, which can be a category (work), a source (agents/parry), or a shared project tag (projects/<slug>); add page: 2 to continue a long box, since: "<latest from the last open>" for a delta view (only newer notes; every open returns latest as the next cursor), and detail: "full" for whole notes (compact opens mark cut notes truncated: true).
configure_profile_search	A point lookup. query is the search text (omit or "*" to list a whole box). source filters by origin: imports/chatgpt, agents/parry. A bare provider name (chatgpt, claude, gemini, grok, other) searches both that agent's shelf and the matching import shelf; use agents/<name> or imports/<provider> for an exact filter. Category lookups use box, not source.
configure_profile_remember	Save one durable fact. It follows the user to every Configure app.
configure_profile_commit	Write back what a conversation learned, attributed to your agent.
configure_profile_forget	Delete a memory by id, with a reason. user_request suppresses it for good.
configure_profile_import	Bulk-save a chunk of context (a transcript, long note, multi-topic dump). Configure distills it into one note in a box. Use it instead of many remember calls.
configure_gmail_search	Search their mail.
configure_email_send	Send mail as them.
configure_calendar_get / configure_calendar_create_event	Read and create events.
configure_drive_search / configure_notion_search	Search their files and notes.
configure_connect	Mint a sign in or connect-an-app link when the user isn't connected yet. Never build these links yourself.

Calling the tools

Over MCP these are native tools. Your model calls one by name, configure_profile_read, with a JSON arguments object, exactly like any other MCP tool it is offered. You do not write a function call yourself. The code samples below use the SDK's profile.executeTool() to show the shape of each call; that is the surface for apps that embed Configure in their own model loop. An MCP client just invokes the tool by name.

• box vs source. A source box id (agents/<name>, imports/<provider>) works as box in read and as source in search. In remember, box names a shelf inside your own namespace (or a shared projects/<slug> tag); it does not address another source. Notes written over MCP carry a server-stamped session field on box opens: the authenticated way to tell sessions of one agent apart. Category boxes (work, preferences-and-taste) are box-only.
• What configure_profile_read returns. Identity and a synthesized narrative, preferences and writing style, a connections map, the top facts (each tagged with its [box]), changesSince (what was saved after the summary was written), and a boxes table of contents on three shelves: category boxes, source boxes, and project boxes (projects/<slug>). Apps that are not connected carry a connect_hint telling you the exact configure_connect call that fixes it. The read is bounded to a fixed budget and sets truncated with the box ids that hold the rest.
• Write, then forget. remember, commit, and import each return a mem_… id; configure_profile_forget takes that id. Reach for remember for one fact the user stated, commit for what a whole turn inferred, import for a bulk dump.

Arguments for the writes and delete (everything else is shown in the examples below):

Tool	Arguments
configure_profile_remember	fact (required), box (optional; defaults to other)
configure_profile_commit	memories, messages, toolResults, read_id (all optional; pass what the turn produced)
configure_profile_import	text (required), box (optional)
configure_profile_forget	id (required), date (optional, YYYY-MM-DD; skips the namespace scan), reason (optional, default correction; user_request suppresses for good)

The patterns

Pre turn. Read once before the agent's first message, not every turn:

// SDK form shown; over MCP, call the native tool `configure_profile_read`
const ctx = await profile.executeTool({ name: "configure_profile_read", arguments: {} });
agent.system(`About the user:\n${JSON.stringify(ctx)}`);

Remember as you go. When the user states something durable, save it in the moment, one fact per call:

await profile.executeTool({ name: "configure_profile_remember", arguments: { fact: "Prefers weekly summaries on Friday" } });

Search for specifics. Reach for configure_profile_search when the question is concrete ("what does my ChatGPT know about my writing style") instead of re-reading the whole profile:

await profile.executeTool({ name: "configure_profile_search", arguments: { query: "writing style", source: "imports/chatgpt" } });

Hand off between agents. Save notes with a shared box: "projects/<slug>" and any agent the user has permitted can read the thread back with one open. Each note is attributed to the agent that wrote it:

await profile.executeTool({ name: "configure_profile_remember", arguments: {
  fact: "[handoff] auth refactor done; next: wire the settings page",
  box: "projects/configure.dev",
} });
// later, from a different agent:
const thread = await profile.executeTool({ name: "configure_profile_read", arguments: { box: "projects/configure.dev" } });

Projects: shared working context across agents. Notes saved with box: "projects/<slug>" form a shared, per-note-attributed project view that any of the user's approved agents can open. This is the handoff pattern that replaces pasting transcripts between coding agents:

// leave the baton
await profile.executeTool({ name: "configure_profile_remember", arguments: {
  fact: "[handoff] Billing wired, webhooks flaky. Next: idempotency keys. Repo: configure, branch billing-v2. (my-agent, 2026-07-19)",
  box: "projects/configure",
} });

// pick it up (any agent; falls back to search on older servers)
const notes = await profile.executeTool({ name: "configure_profile_read", arguments: { box: "projects/configure" } });

Full pattern, note types, and trust rules: Projects.

Gate on connections. configure_profile_read returns a connections map (and detailed integrations). Only offer Gmail or Calendar actions when connections.gmail or connections.calendar is true; when it's false, the integration entry carries a connect_hint and configure_connect returns the link that fixes it.

Handle the configure_connect statuses. The tool answers with a status, a connect_url, and instructions. Include the connect_url in your reply verbatim. Links expire (about an hour), and only the server mints them.

Status	Meaning	What you do
connect_app	User is signed in; the link opens the connect flow for app (the result echoes app and whether it is already connected).	Share the link. When the link targets one app, the page routes straight to that app after any sign-in.
authorization_required	User is not signed in yet. With app set, the result still carries the app and the link signs them in, then continues to that app.	Share the link. Do not retry while they sign in; call the tool again once they say they finished.
session_probe_required	The client has not established its MCP session yet.	Call again once the session handshake completes.
permission_needed	A connector call hit a missing capability (for example send-only email access). The result names the capability, a human purpose, and a minted link that requests exactly that permission.	Share the link with the purpose. Call the tool again after the user grants it.

A connector tool call for an app that is not connected fails closed with an error telling you the app is not connected; call configure_connect with that app to mint the link. Permission upgrades for a single capability (for example send-only email access) ride the same minted-link rail and return status: "permission_needed" with the capability named.

For the sign in flow that gets your users here, see Sign in with Configure.

MCP or SDK

MCP connects an AI client. The TypeScript SDK is for building Configure directly into your app after choosing For my users in setup.

Use the SDK when you own the app UI, auth flow, and model loop. Use MCP when the client already expects tools through the MCP protocol.

Next: Configure as an MCP adapter.