# wflow-mail-mcp

> Agent instructions for connecting to this remote MCP mail server.

## Setup

1. Treat the URL where this file was fetched as the MCP server base URL.
2. Configure the remote MCP endpoint at the same base URL with the path '/mcp'.
3. Use the server's OAuth discovery endpoints to begin authorization.
4. Open the authorization URL in the user's external browser.
5. Tell the human that authentication requires only a valid email address and an application password for that mailbox.
6. Before opening authorization, create a temporary callback listener bound only to 127.0.0.1 on an available port. Use its exact redirect URI, including port and path, when registering the client.
7. Generate a fresh PKCE verifier, S256 challenge, and state value for every authorization request, and retain them only for that flow.
8. Start monitoring the callback listener before opening the browser. The listener must accept one callback, parse its query parameters, and pass the result back to the authorization workflow.
9. Treat a callback containing both code and the matching state as authorization success. Do not wait for the browser page to finish loading, do not inspect its rendered text, and do not ask the human to report success.
10. Automatically exchange the callback's authorization code and PKCE verifier at /oauth/token, initialize the MCP session at /mcp, and continue with the requested mail operation using the returned bearer token.
11. If the callback contains an OAuth error, report that error and stop. Never exchange a code whose state does not match, and never reuse an authorization code, verifier, or token from another flow.
12. After receiving the first valid callback or a terminal error, shut down the temporary listener. Apply a bounded timeout if no callback arrives.

### Callback browser response

The callback listener is the source of truth. After receiving the callback, return a short HTML response such as "Anmeldung empfangen – die Verbindung wird eingerichtet. Dieses Fenster kann geschlossen werden." Do not display the authorization code, state, access token, refresh token, mailbox password, or raw upstream error. The browser response is only a human-friendly acknowledgement; token exchange, MCP initialization, and success detection happen in the agent workflow.

Do not ask the user to send the password in chat or as an MCP tool argument. The user must enter it only on the server's authorization page.

After authentication, the available tools are 'list_folders', 'search_messages', 'read_message', 'get_message_headers', 'list_attachments', 'get_attachment', 'flag_message', 'move_message', 'draft_message', and 'send_message'.