--- canonical_url: https://docs.configure.dev/mcp/headless last_updated: 2026-10-31 --- # 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](https://docs.configure.dev/mcp/overview.md) instead. Configure connects your agent to your user's other agents and apps, with the user's approval. Connect once, then read and add to their context 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. ```json {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"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): ```json {"jsonrpc":"2.0","method":"notifications/initialized"} ``` **2. Get the approval link.** ```json {"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 an hour 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: ```json {"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 only 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/`, 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.