Authentication
The hosted server at https://heylead.dev/mcp uses OAuth 2.1. Your client opens the browser, you sign in with Google and choose a workspace on the consent page, and the client keeps a token. You never paste a password or a token into a chat.
Discovery
- Protected resource:
https://heylead.dev/.well-known/oauth-protected-resource - Authorization server:
https://heylead.dev/.well-known/oauth-authorization-server
The authorization server metadata names the endpoints: /oauth/authorize, /oauth/token, /oauth/register (dynamic client registration, so a client needs no pre-shared id) and /oauth/revoke. PKCE with S256 is required; the response type is code; grants are authorization_code and refresh_token.
Scopes
| Scope | What it allows |
|---|---|
outreach:read |
Read campaigns, contacts, replies, results and status. A read-only connection can draft and show but never send. |
outreach:write |
Create and change campaigns, approve messages, send as you, launch and stop. |
Token life
An access token lives one hour and is bound to this server. The refresh token lives 90 days; your client refreshes without asking you again. An authorization code lives 60 seconds.
Revoking
Revoke a client from HeyLead Settings in the dashboard, or through /oauth/revoke. A revoked refresh token stops the client at the next refresh.
The local client
The Python client (uvx heylead) talks to the hosted backend with a private setup message from Settings → Integrations → Chat client → Local Python client; it contains a sign-in token, so paste it only into your own agent. This path does not use OAuth. See Self-hosting.