MCP Authentication
FunnelStory authenticates MCP clients using OAuth 2.0 with PKCE. This is the same browser-based authorization flow used across enterprise software — your credentials stay in FunnelStory, and the client receives a short-lived access token tied to you and one workspace.
The Authorization Flow
When an MCP client connects for the first time:
- The client fetches OAuth metadata from
/.well-known/oauth-authorization-serverto discover FunnelStory's authorization endpoints - The client registers itself using Dynamic Client Registration (DCR) — no manual setup needed
- The client redirects you to FunnelStory's authorization page
- You log in (if not already) and approve the access request
- The client exchanges the authorization code for an access token
- The client uses that token for all subsequent requests to
/api/mcp
After the initial setup, the client refreshes its token automatically. You'll need to authorize again only if you revoke access or the client goes unused for 7 days.
Token Lifetimes
| Token | Lifetime | Notes |
|---|---|---|
| Access token | 15 minutes | Sent with every MCP request. The token response includes expires_in: 900. |
| Refresh token | 7 days from issue | Single use. Every refresh returns a new refresh token and invalidates the one used. Reusing an old refresh token is rejected. |
A client that refreshes regularly keeps working without asking you to log in again. Each new refresh token starts a fresh 7-day period.
What a Token Can Access
FunnelStory doesn't use OAuth scopes. A token is tied to the user who authorized it and the workspace they chose. Every tool call runs with that user's role and permissions, including CRM-based account visibility, exactly as in the FunnelStory app. Each tool call is also recorded in the workspace Audit Log.
PKCE
PKCE (Proof Key for Code Exchange) protects the authorization flow in environments where a static client secret can't be kept confidential — like desktop apps. It prevents authorization codes from being used even if they're intercepted mid-flow.
Revoking Access
To remove a client's access to your workspace:
- Go to the profile menu (avatar) → MCP Clients
- Find the client and click the delete icon
The client's tokens are invalidated immediately.
For Custom MCP Clients
If you're integrating a custom client with FunnelStory's OAuth server:
| Endpoint | Standard |
|---|---|
/.well-known/oauth-authorization-server | RFC 8414 |
/.well-known/oauth-protected-resource | RFC 9728 |
Dynamic Client Registration is supported — clients discover the registration endpoint from the server metadata.
Next Steps
- Getting Started — connect your MCP client
- Available Tools — what authenticated clients can access