Getting started

Prerequisites

SSR mode - EventCatalog must run in server mode (not static)

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/

The server accepts URLs with or without a trailing slash (/docs/mcp and /docs/mcp/).

To find your server URLs in EventCatalog, open Settings > MCP. It lists the Catalog MCP Server and, under Domain MCP Servers, the MCP server of each domain, each with its full URL to copy.

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.

On a scoped server, tools only return resources in that scope, and an omitted version means the latest version in that domain or system.

Scoped tool availability

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

Disable the MCP server

The built-in MCP server is enabled by default when EventCatalog is running in server mode. 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.3.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

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

Claude Code

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

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

Cursor

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

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

VS Code

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

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

Available tools

22 built-in tools

Every built-in tool is read-only (readOnlyHint: true) and has a title, so MCP clients can show readable names and auto-approve the tools. Version parameters are optional on every tool: omit them (or pass latest) to use the latest version.

The server also sends instructions to clients on how to navigate the catalog, for example to use showResource when the user wants to see a diagram or schema.

Tool	Title	What it does	Scoped servers
`getResources`	List catalog resources	Lists resources in a collection, with pagination (`cursor`) and an optional `search` term	Yes
`getResource`	Get a catalog resource	Returns a resource's frontmatter and markdown as `{ id, version, collection, data, body }`	Yes
`getMessagesProducedOrConsumedByResource`	Get messages a resource sends and receives	Returns the messages a service, agent or domain sends and receives, resolved to their catalog entries. `resourceCollection` defaults to `services`	Yes
`getSchemaForResource`	Get schemas and specifications	Returns the schemas or OpenAPI/AsyncAPI/GraphQL specifications of a resource, for the model to read. `resourceCollection` defaults to `services`	Yes
`showResource`	Show a resource	Shows the user a resource's architecture diagram or schema. See Interactive diagrams and schemas	Yes
`findResourcesByOwner`	Find resources by owner	Finds resources owned by a team or user	Yes
`getProducersOfMessage`	Find producers of a message	Finds the services and agents that send a message. `messageCollection` defaults to `events`	Yes
`getConsumersOfMessage`	Find consumers of a message	Finds the services and agents that receive a message. `messageCollection` defaults to `events`	Yes
`analyzeChangeImpact`	Analyze the impact of changing a message	Returns the affected producers and consumers, their owning teams and the blast radius of a change	Yes
`explainBusinessFlow`	Explain a business flow	Returns a flow's definition, steps and related services and agents	Yes
`findMessageBySchemaId`	Find a message from a schema	Finds a message from the `x-eventcatalog-id` (and optional `x-eventcatalog-version`) in a schema	Yes
`explainUbiquitousLanguageTerms`	Explain ubiquitous language terms	Returns the ubiquitous language terms of a domain and its subdomains	Domain servers only
`getC4Diagram`	Get C4 (LikeC4) diagrams	Returns the source of your C4 (LikeC4) diagrams	No
`getTeams` / `getTeam`	List teams / Get a team	Lists teams, or gets a team with its members	No
`getUsers` / `getUser`	List users / Get a user	Lists users, or gets a user with their role and contact details	No
`getDataProductInputs`	Get data product inputs	Returns the resources a data product consumes	No
`getDataProductOutputs`	Get data product outputs and contracts	Returns the resources a data product produces, with their data contracts	No
`getCustomDocs`	List custom documentation	Lists custom documentation pages, with pagination and an optional `search` term	No
`searchCustomDocs`	Search custom documentation	Full-text search across custom documentation pages	No
`getCustomDoc`	Get a custom documentation page	Returns a custom documentation page, or one `section` of it	No

showResource, getDataProductInputs and getDataProductOutputs were added in EventCatalog 5.0.0.

In clients that support MCP Apps, the server also registers getResourceView. The viewer uses this app-only tool to load diagrams and schemas. The model doesn't call it.

Interactive diagrams and schemas

Added in eventcatalog@5.0.0

The showResource tool shows the user a resource in EventCatalog's viewer. Ask your agent things like "show me how the Order Service works" or "show me the schema for OrderCreated".

Parameter	Required	Description
`view`	Yes	`"architecture"` for an architecture diagram, or `"schema"` for the schema of a message or other resource
`resourceId`	Yes	The id of the resource to show
`resourceVersion`	No	The version to show. Defaults to the latest version
`resourceCollection`	No	The collection of the resource, for example `services`, `domains` or `events`. Defaults to `events`
`detail`	No	For `view: "architecture"` of domains and systems: `"overview"` shows only the domains, systems and their relationships (level 1). `"full"` (default) also shows services, messages and channels

With view: "architecture", the diagram is built the same way as the resource's Diagram page in EventCatalog. You can show diagrams of domains, systems, services, agents, events, commands, queries, flows, data stores and data products.

In MCP clients that support MCP Apps (for example Claude, ChatGPT and VS Code):

Architecture diagrams open in the interactive visualiser. You can switch levels, search, open other resources' diagrams, and click a node to ask the conversation a question about it.
Schemas open in the same viewer as the Schema Explorer: a Schema tab with the highlighted source, and a Properties tab for JSON Schema, Avro and Protobuf that you can search and expand. Messages with several schemas can switch between them.

Diagrams and schemas share one viewer. Clients such as ChatGPT keep that viewer open and switch it to each diagram or schema you ask for. The viewer asks the client to open it full screen.

Other MCP clients get the diagram as Mermaid code and the schema as code, which the agent can show you.

Showing schemas vs reading schemas

Use showResource with view: "schema" when a person wants to see a schema. getSchemaForResource returns the raw schemas and specifications for the agent to read, for example to generate code.

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 license key
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 license key
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.

Prerequisites​

Quick start​

Connect to a domain or system​

Disable the MCP server​

Verify the server​

Protect with OAuth​

Key signing options​

All options​

Connect clients​

Available tools​

22 built-in tools​

Interactive diagrams and schemas​

17 resources​

Add custom tools​

Use standalone server​