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 connects this agent to the user's other agents and apps. After the user approves access, MCP tools can read permitted profile context and save new context for other approved agents.

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 MCP client manages OAuth sign-in and exposes the Configure tools.

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 contains connect_url and expires_at. The URL expires after approximately 30 minutes. The approved session has a separate lifetime, described 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. Verify authorization after the user confirms approval. 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":{}}}

• A successful call confirms authorization. Call tools/list to retrieve available tools.
• 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 create 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

Authorization is associated with Mcp-Session-Id. Store the header value as a secret so the agent can reuse the authorization after a restart. 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.

Authorization requirements

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