• 

• 

• 

• 

EspoCRM-MCP-Auth0 - Enterprise-Grade AI Assistant Integration for CRM with Auth0 & FGA

Inspiration

As AI assistants like Claude and ChatGPT became increasingly capable, we recognized a growing need to integrate them with business-critical CRM systems. However, existing integration approaches required each user to deploy their own server instance with their own API key - a solution that didn't scale for enterprise environments.

We realized that Auth0 could provide centralized identity management with access token validation, OAuth authorization code flow, and scope-based authorization - capabilities that were missing from traditional API key approaches. By combining Auth0 with the Model Context Protocol (MCP), we could create a single server that serves multiple users securely.

More importantly, we discovered Auth0's Fine-Grained Authorization (FGA) service. While OAuth scopes only answer "Can user X read contacts?", FGA answers "Can user X read contact #123?" - providing entity-level permission control based on relationships like ownership, team membership, and management hierarchy.

This powerful combination - Auth0 for centralized authentication plus FGA for fine-grained authorization - inspired us to build a system where AI assistants can safely interact with CRM data in multi-user, enterprise environments without exposing API keys to end users.

What it does

EspoCRM-MCP-Auth0 is an MCP server that enables AI assistants to interact with EspoCRM through natural language while enforcing enterprise-grade security. The project includes:

Auth0 Centralized Identity: Provides access token validation, OAuth authorization code flow, and scope-based authorization through Auth0 Universal Login Page.

Auth0 FGA Fine-Grained Authorization: Uses Auth0's Fine-Grained Authorization (FGA) service to enforce entity-level permissions based on relationships (assigned, manager, etc.), supporting complex organizational structures with dynamic permission computation.

Multi-Layer Security Architecture: Combines Auth0 authentication, OAuth scope-based authorization (coarse-grained), and FGA entity-level permissions (fine-grained) to provide defense-in-depth security.

Seamless AI Integration: Implements the Model Context Protocol (MCP) to expose CRM operations as tools that AI assistants can invoke through natural language conversations.

Service Account Pattern: Uses a single EspoCRM service account with user permissions enforced at the MCP layer, keeping API keys secure and enabling external user access.

How we built it

The project was built through four key phases:

Phase 1 - MCP and EspoCRM Integration: We started by implementing the core MCP server that exposes EspoCRM operations as tools. Each CRM operation (create contact, search accounts, get lead details) became an MCP tool with clear descriptions so AI assistants know when and how to use them. We built an EspoCRM API client supporting both API key and HMAC authentication methods.

Phase 2 - Auth0 Authentication & Authorization: We integrated Auth0 for centralized identity management. Every request includes a bearer token (access token) that's validated before any tool executes. We implemented OAuth scopes for coarse-grained authorization, and the server verifies the user's token includes those scopes.

Phase 3 - Auth0 FGA Fine-Grained Authorization: This was the most challenging and innovative phase. We designed an FGA authorization model that captures business rules like "team members can read team entities". The model uses relationship-based access control where permissions are computed dynamically from relationships.

Phase 4 - Production Readiness: We focused on making the system production-ready with proper error handling, comprehensive documentation, initialization scripts for easy deployment, and optional FGA support that gracefully falls back to scope-only authorization when FGA isn't configured.

Challenges we ran into

Authorization with Auth0 & FGA: The challenge was enforcing user-level permissions when using a single service account to connect to EspoCRM. We solved this by implementing Auth0 for user identity and OAuth scopes for API-level authorization, then adding FGA for entity-level permissions. The service account (EspoCRM API user) has full EspoCRM access, but user permissions are enforced at the MCP server through the Auth0 + FGA combination before requests reach EspoCRM.

FGA Permission Synchronization: FGA needs to know about every entity and its relationships. We implemented initialization scripts for setup that create sample authorization tuples. The FGA client also provides helper methods for syncing entity permissions, though these are not yet integrated into the MCP tool workflow.

CherryStudio MCP Client Integration: We first debugged our OAuth implementation using MCP Inspector's built-in OAuth flow. Then we configured the same MCP server in CherryStudio, where the OAuth authorization page automatically opened in the browser for user login, demonstrating seamless cross-client compatibility. However, we discovered a CherryStudio bug: it cannot clear previously authorized tokens, forcing users to manually delete JWT files from ~/.cherrystudio/config/mcp/oauth to re-authorize. This issue took significant time to identify and debug. See https://github.com/CherryHQ/cherry-studio/issues/14047

Backward Compatibility: Not all users need FGA - some only want scope-based authorization. We made FGA completely optional with graceful fallback, allowing gradual adoption starting with scopes and adding FGA when needed.

Accomplishments that we're proud of

Auth0-Powered Identity Management: Successfully replaced scattered API keys with centralized Auth0 identity management, implementing JWT token validation, OAuth authorization code flow, and scope-based authorization.

Auth0 FGA-Powered Fine-Grained Authorization: Achieved entity-level permission control using Auth0's FGA service with relationship-based access model, supporting complex organizational structures with team hierarchies, management relationships, and dynamic permission computation without code changes.

Defense-in-Depth Security: Successfully implemented a three-layer security model - Auth0 authentication, OAuth scopes (coarse-grained), and FGA (fine-grained) - providing multiple independent security layers that protect business-critical CRM data.

Scalable Architecture: Built a single-server architecture that serves multiple users through centralized identity management, eliminating the need for per-user deployments and API key distribution.

Seamless AI Experience: Created a natural language interface (MCP Server) where users can interact with CRM data through conversations with AI assistants, with all security enforcement happening transparently in the background.

What we learned

Auth0 Identity Platform: We learned how to leverage Auth0 for centralized identity management with JWT token validation, OAuth authorization code flow, and scope-based authorization.

Auth0 FGA Relationship-Based Authorization: We gained deep insights into modeling complex permission scenarios using Auth0's FGA service with relationship-based access control.

Defense-in-Depth Security: We learned that robust security requires multiple independent layers. The combination of Auth0 (authentication), OAuth scopes (coarse-grained authorization), and FGA (fine-grained authorization) creates a security architecture where even if one layer fails, others provide protection. This principle is essential for enterprise systems handling sensitive business data.

OAuth Integration Patterns: We deepened our understanding of OAuth 2.0 flows, token validation, scope-based authorization, and how to implement seamless authentication experiences for AI clients.

What's next for EspoCRM-MCP-Auth0

FGA Permission Synchronization Integration: The sync_entity_permissions() helper method exists in the FGA client but is not yet wired into the MCP tool workflow.

Real-Time Synchronization: Implement webhook integration to keep FGA permissions in sync with EspoCRM data changes in real-time, ensuring authorization stays consistent with data.

Bulk Operations: Add support for batch create, update, and delete operations with efficient permission checking across multiple entities.

Admin Interface: Build a web-based admin UI for managing FGA permissions, viewing authorization relationships, and troubleshooting access issues.

---

Bonus Blog Post

How Token Vault Changed Our Approach to AI Agent Authorization

This blog post is submitted as part of the Authorized to Act Hackathon Bonus Blog Post Prize category.

The Problem We Kept Postponing

When we started building EspoCRM-MCP-Auth0, we thought the hard part would be the MCP integration. We were wrong.

The real challenge wasn't getting AI to talk to CRM - it was getting AI to talk to CRM securely on behalf of real users. Every AI agent tutorial shows you how to hardcode an API key. Nobody tells you what happens when you have 50 users, 3 teams, and a manager who needs to see their team's contacts but not the CEO's pipeline.

That's exactly where Token Vault came in.

Why Token Vault Changed the Game

1. The Service Account Pattern That Actually Works

We use a single EspoCRM service account - no per-user API keys. But how do you enforce user permissions? Auth0 identifies who the user is, FGA determines what they can do, and Token Vault keeps the service account's credentials secure while letting the agent act on behalf of individual users. Token Vault is the security boundary between the agent and the credentials.

2. OAuth Flows for AI Agents

AI agents don't have browsers. Humans do. Token Vault handles the asynchronous OAuth dance - the agent requests access, Token Vault generates a URL, the user authorizes, and the agent gets tokens without ever touching credentials. This sounds simple in documentation. In practice, it's the difference between "works on my laptop" and "works in production."

The "Aha" Moment

The moment everything clicked was when we tested a scenario: User A (sales rep) asks "what's the status of contact Alex?" while User B (manager from another team) asks the same question. Both went through the same MCP server, same service account, same EspoCRM API. But User A got the contact details. User B got "access denied."

Token Vault made this possible because each request carried a user-specific context - tokens obtained through Auth0, permissions checked through FGA, with Token Vault handling the underlying credential plumbing.

What We'd Tell Other Builders

If you're building AI agents that touch customer data: Start with Token Vault day one. Retrofitting OAuth flows is painful. Auth0 handles "who is this?" FGA handles "what can they do?" Together they answer the only question that matters: "should this agent execute this action, for this user, on this data?"

Token Vault saved us weeks of token plumbing — we shipped authorization faster than we thought possible.

Built With

• auth0
• cherrystudio
• fga
• mcp
• python