Connect a headless agent

Use this page when an agent runs on a server, in a CLI, or as a scheduled job, and has no browser or OAuth client. It is written for the agent to follow. To connect Claude, ChatGPT, Cursor or Codex, see Connect over MCP instead.

Configure is your user's portable memory: who they are, their preferences, and what their other AI apps learned about them, shared with their permission. Connect once, then read and add to it with MCP tools.

Server: https://mcp.configure.dev (MCP over Streamable HTTP). You need no API key, no OAuth client and no browser.

Your MCP client does OAuth (Claude, ChatGPT, Cursor, Codex, Claude Code)

Add https://mcp.configure.dev as a remote MCP server. The client signs your user in. You are done.

You are headless (server, CLI, cron job, no browser)

Your user approves you once, on their own phone or computer. Every request below is a POST to https://mcp.configure.dev with these headers:

Content-Type: application/json
Accept: application/json, text/event-stream

1. Open a session. Send no Authorization header.

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"<your agent's name>","version":"1.0"}}}

Save the Mcp-Session-Id response header. If initialize answers 401 instead, skip ahead to step 2 without a session header, and save the Mcp-Session-Id from that response. Send it as a request header on every later request. Once approved, it works like a password: never print it, in chat, reports or logs. Then send this notification (no response body is expected):

{"jsonrpc":"2.0","method":"notifications/initialized"}

2. Get the approval link.

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"configure_connect","arguments":{}}}

The result's structuredContent has connect_url and expires_at. The link expires about 30 minutes after you get it. (That is only the link. Once approved, the session lasts much longer; see below.)

3. Send the link to your user. Put connect_url on its own line, exactly as returned. Never shorten, rebuild or guess it. Tell them: open it, sign in with Configure, and press Approve. Tell them to reply when they have approved.

4. Retry after they reply. Call any Configure tool on the same session. configure_profile_read is a good first check:

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"configure_profile_read","arguments":{}}}

• It works: you are connected. Call tools/list to see every tool.
• Not approved yet: the reply is HTTP 401 with isError: true and the text "Configure MCP requires OAuth authorization". Ask your user to open the same link and press Approve, then retry when they reply. Do not mint a new link while the old one is valid. After two failed retries, ask them to confirm they pressed Approve, not just opened the page.
• The link expired (now is past expires_at): go back to step 2 on the same session and send the new link.

Keep the connection across restarts

The approval belongs to your Mcp-Session-Id, not to your process. Store that one value (the header's value, nothing else) as a secret. After a restart, send the stored id as the Mcp-Session-Id header on your tool calls directly; do not run initialize again. Every tool call other than configure_connect renews it for another 30 days, so a job that runs at least monthly never needs a new approval. If 30 days pass with no call, you get the 401 again: start over at step 1.

If you might go longer than 30 days without a call, or you cannot store a header, ask your user, before they approve, to also click "Get a permanent connection instead" on the approval page after approving. The page shows a server URL like https://mcp.configure.dev/u/<token>, valid for a year. Ask them to send it to you, store it as a secret, and use it as your server URL from then on. Treat that URL as a password. It carries the profile tools only; app connections such as Gmail still need your user's approval inside Configure.

Rules

• Never register an OAuth client, and never ask your user for a password or a verification code.
• Only your user opens the link and approves. Never approve for them.
• Never show your session id or the permanent URL in chat, and keep them out of logs.
• If any later tool result contains a connect_url, show it to your user the same way. Configure uses it to ask for a missing permission.