Getting started

View as Markdown

---

i

This feature requires an EventCatalog Scale license.

Start a 30-day trial

Prerequisites

1. SSR mode - EventCatalog must run in server mode (not static)
2. Scale license - You can get a 30-day free trial at eventcatalog.cloud

Quick start

The MCP server for your whole catalog is available at:

https://your-eventcatalog.com/docs/mcp/

For local development:

http://localhost:3000/docs/mcp/

Connect to a domain or system

Domain and system pages include a Connect to MCP server action when the built-in MCP server is available. Select it to see and copy the scoped server URL for that resource.

Scoped MCP servers expose the selected domain or system and resources reachable from it through supported catalog relationships. EventCatalog follows those relationships recursively, giving the MCP client the full reachable graph without including unrelated catalog resources. Scoped MCP URLs do not take a depth parameter.

Scope	Latest version	Specific version
Domain	/docs/mcp/domains/{domain-id}	/docs/mcp/domains/{domain-id}/{version}
System	/docs/mcp/systems/{system-id}	/docs/mcp/systems/{system-id}/{version}

For example:

https://your-eventcatalog.com/docs/mcp/domains/payments
https://your-eventcatalog.com/docs/mcp/systems/payment-processing/1.2.0

The unversioned URL follows the latest version of the domain or system. When you view a historical version in EventCatalog, the connection action uses the versioned URL instead.

You can use a scoped URL anywhere the client examples below use the whole-catalog /docs/mcp/ URL.

Scoped tool availability

Scoped servers omit C4, team and user directory, custom documentation, and user-defined extended tools. System-scoped servers also omit the domain-specific ubiquitous-language tool.

Disable the MCP server

The built-in MCP server is enabled by default when EventCatalog is running in server mode with a Scale license. To disable the whole-catalog endpoint, scoped endpoints, and MCP connection actions, set mcp.enabled to false:

eventcatalog.config.js

module.exports = {
  output: 'server',
  mcp: {
    enabled: false,
  },
};

Verify the server

Visit the endpoint in your browser to verify. It returns available tools and resources:

{
  "name": "EventCatalog MCP Server",
  "version": "1.2.0",
  "status": "running",
  "tools": ["getResources", "getResource", ...],
  "resources": ["eventcatalog://all", "eventcatalog://events", ...]
}

The MCP server uses stateless Streamable HTTP. MCP protocol requests use POST; an ordinary browser GET returns the health response above. A client requesting a server-sent events stream with GET receives 405 Method Not Allowed because this stateless server does not provide the optional SSE channel.

Protect with OAuth

Added in eventcatalog@3.40.0

The built-in MCP server can be protected with OAuth Bearer tokens, following the MCP authorization specification for HTTP transports.

EventCatalog acts as the OAuth protected resource server for /docs/mcp. Your identity provider or authorization server remains responsible for user login, consent, client registration, /authorize, /oauth/token, and token refresh.

The same authorization configuration protects the whole-catalog endpoint and every scoped domain and system endpoint. Configure resource and audience for the catalog MCP resource at /docs/mcp; you do not need separate OAuth configuration for each scope.

Configure MCP authorization in eventcatalog.config.js:

eventcatalog.config.js

module.exports = {
  output: 'server',
  mcp: {
    auth: {
      enabled: true,
      resource: 'https://your-eventcatalog.com/docs/mcp',
      authorizationServers: ['https://auth.example.com'],
      issuer: 'https://auth.example.com',
      audience: 'https://your-eventcatalog.com/docs/mcp',
      requiredScopes: ['catalog:read'],
      jwksUri: 'https://auth.example.com/.well-known/jwks.json',
    },
  },
};

When enabled, EventCatalog serves protected resource metadata at /.well-known/oauth-protected-resource. Unauthenticated MCP clients receive a 401 Unauthorized response with a WWW-Authenticate header pointing at that document. MCP clients then obtain an access token from the advertised authorization server and call /docs/mcp with:

Authorization: Bearer <access-token>

The access token must be valid, unexpired, issued by the configured issuer, intended for the configured audience, and include all required scopes.

Key signing options

Choose one of the following strategies for token validation:

Strategy	Config fields
JWKS endpoint (recommended)	jwksUri
Inline asymmetric public key	publicKey or publicKeyEnvVar
Symmetric shared secret	sharedSecret or sharedSecretEnvVar

Prefer publicKeyEnvVar or sharedSecretEnvVar over inline values to avoid committing secrets to source control.

All options

Field	Required	Description
enabled	Yes	Enables OAuth Bearer token validation
resource	No	Absolute URL of the MCP resource. Set this explicitly when behind a proxy
protectedResourceMetadataUrl	No	URL for the protected resource metadata document. Defaults to /.well-known/oauth-protected-resource
authorizationServers	No	Authorization server URLs advertised to MCP clients
issuer	No	Expected token issuer (iss claim)
audience	No	Expected token audience (aud claim). Defaults to resource
requiredScopes	No	Scopes every token must include
jwksUri	No	JWKS endpoint for asymmetric JWT validation
publicKey	No	Inline public key for asymmetric JWT validation
publicKeyEnvVar	No	Environment variable containing the public key
sharedSecret	No	Inline shared secret for symmetric JWT validation
sharedSecretEnvVar	No	Environment variable containing the shared secret

Existing website authentication

The auth.enabled and eventcatalog.auth.js settings protect the EventCatalog website with browser sessions. MCP authorization is separate because MCP clients authenticate with Bearer tokens, not browser cookies.

Authorization server discovery

EventCatalog serves /.well-known/oauth-protected-resource for MCP client discovery. It does not serve /.well-known/oauth-authorization-server, /authorize, or /oauth/token -- those endpoints must be provided by the authorization server listed in authorizationServers. If your MCP client expects those endpoints on the catalog host, proxy the authorization server behind that host with your load balancer or reverse proxy.

Connect clients

Claude Desktop

1. Get your MCP URL https://your-eventcatalog.com/docs/mcp/
2. Navigate to the Connectors page in Claude Settings.
3. Select Add custom connector
4. Select Add
5. When using Claude, select the attachments button (the plus icon).
6. Select your MCP server.

Claude Code

1. Get your MCP URL https://your-eventcatalog.com/docs/mcp/
2. Run the command to connect claude code to your eventcatalog instance

claude mcp add --transport http <name> <url>

Cursor

1. Get your MCP URL https://your-eventcatalog.com/docs/mcp/
2. Use Command + Shift + P (Ctrl + Shift + P on Windows) to open the Command Palette.
3. Search for "Open MCP settings"
4. Select Add custom MCP. This opens the mcp.json file.
5. Add the following to the mcp.json file:

{
  "servers": {
    "<your-mcp-server-name>": {
      "url": "https://your-eventcatalog.com/docs/mcp/"
    }
  }
}

VS Code

1. Get your MCP URL https://your-eventcatalog.com/docs/mcp/
2. Create a .vscode/mcp.json file.
3. Inside the mcp.json file, add the following:

{
  "servers": {
    "<your-mcp-server-name>": {
      "type": "http",
      "url": "https://your-eventcatalog.com/docs/mcp/"
    }
  }
}

Available tools

19 built-in tools

• getResources - Get events, services, commands, queries, flows, domains
• getResource - Get a specific resource by id and version
• getMessagesProducedOrConsumedByResource - Messages a resource sends/receives
• getSchemaForResource - Get OpenAPI, AsyncAPI, or other schemas
• findResourcesByOwner - Resources owned by a team or user
• getProducersOfMessage - Services that produce a message
• getConsumersOfMessage - Services that consume a message
• getC4Diagram - Get the source for a C4 diagram
• analyzeChangeImpact - Impact of changing a message
• explainBusinessFlow - Detailed flow information
• getTeams / getTeam - Query teams
• getUsers / getUser - Query users
• findMessageBySchemaId - Find messages by schema identifiers
• explainUbiquitousLanguageTerms - DDD ubiquitous language from domains
• getCustomDocs - List and search custom documentation pages
• searchCustomDocs - Full-text search custom documentation
• getCustomDoc - Get a custom documentation page or section

See full API documentation →

17 resources

• eventcatalog://all - All resources
• eventcatalog://events - All events
• eventcatalog://commands - All commands
• eventcatalog://queries - All queries
• eventcatalog://agents - All agents
• eventcatalog://adrs - All architecture decision records
• eventcatalog://services - All services
• eventcatalog://systems - All systems
• eventcatalog://channels - All channels
• eventcatalog://entities - All entities
• eventcatalog://diagrams - All diagrams
• eventcatalog://containers - All containers
• eventcatalog://data-products - All data products
• eventcatalog://domains - All domains
• eventcatalog://flows - All flows
• eventcatalog://teams - All teams
• eventcatalog://users - All users

Add custom tools

Extend the MCP server with custom tools in eventcatalog.chat.js:

// eventcatalog.chat.js
export const tools = {
  myCustomTool: {
    description: 'My custom tool for EventCatalog',
    parameters: z.object({
      query: z.string().describe('The query parameter'),
    }),
    execute: async ({ query }) => {
      // Your custom logic here
      return { result: 'Custom data' };
    },
  },
};

Custom tools appear alongside built-in tools automatically.

Use standalone server

For catalogs without SSR mode, use the standalone @eventcatalog/mcp-server package. We plan to deprecate this in a future release, so we recommend migrating to the built-in server when possible.

Standalone server on stdio

For local development and testing, you can use the MCP Server on stdio. This is useful for single-client, low-latency tools.

Prerequisites:

• EventCatalog configured with the LLMS.txt feature
• EventCatalog Scale license
• MCP client installed

Command:

npx -y @eventcatalog/mcp-server {URL_TO_YOUR_EVENTCATALOG_INSTANCE} {EVENTCATALOG_LICENSE_KEY}

Standalone server over HTTP

Run the MCP Server over HTTP for production deployments.

Prerequisites:

• EventCatalog instance running
• EventCatalog Scale license
• MCP client installed

Run using npx:

npx -y @eventcatalog/mcp-server https://your-eventcatalog-instance.com {EVENTCATALOG_LICENSE_KEY} http {PORT} {ROOT_PATH}

Example:

npx -y @eventcatalog/mcp-server https://demo.eventcatalog.dev {EVENTCATALOG_LICENSE_KEY} http 3000 /mcp

This starts the MCP Server over HTTP on port 3000 with root path /mcp.

Run using Docker:

See instructions on the GitHub repository.