Connect AI agents

Componecat exists to give AI coding agents the context they’re usually missing: which components exist, how they fit together, who owns them, and how to reach them. It exposes the whole catalog over a Model Context Protocol (MCP) server, so an agent can query the catalog directly, in real time, before it writes code.

The MCP endpoint

The MCP server is served at /api/mcp. For the hosted app that’s:

https://app.componecat.ai/api/mcp

Add it to any MCP-capable client (Claude, an IDE agent, or your own) as a remote MCP server. Because catalogs are private and organization-scoped, the endpoint requires authentication.

The server is published in the MCP registry as com.shaftware/componecat, with its public metadata and stdio bridge at github.com/componecat/mcp.

Connect from your client

VS Code

One-click install: Install in VS Code · Install in VS Code Insiders

Or add to your mcp.json:

{
  "servers": {
    "componecat": { "type": "http", "url": "https://app.componecat.ai/api/mcp" }
  }
}

Claude Code

claude mcp add --transport http componecat https://app.componecat.ai/api/mcp

Claude.ai and Claude Desktop

Add a custom connector under Settings → Connectors → Add custom connector with the URL https://app.componecat.ai/api/mcp.

ChatGPT

Turn on Developer mode under Settings → Security and login, then open ChatGPT Plugins, select the plus button, choose OAuth as the connection method, and enter https://app.componecat.ai/api/mcp. ChatGPT registers itself with Componecat automatically; the first time you use a tool it opens the Componecat approval screen, where you sign in, pick the organization, and choose what the agent may read or write. Enable the app from the Developer mode entry in the composer’s plus menu when starting a conversation.

Cursor

Add to Cursor, or add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "componecat": { "url": "https://app.componecat.ai/api/mcp" }
  }
}

Other clients

Most remote-capable clients accept the endpoint URL directly. For clients that only speak stdio, the @shaftware/componecat-mcp bridge proxies to the remote endpoint (OAuth completes in your browser):

{
  "mcpServers": {
    "componecat": { "command": "npx", "args": ["-y", "@shaftware/componecat-mcp"] }
  }
}

Self-hosted instances: point any of the above at your own host’s /api/mcp (for the bridge, set COMPONECAT_MCP_URL).

Authorizing an agent

Componecat supports the standard MCP authorization flow:

• OAuth device flow — the usual path for interactive agents. The client discovers the authorization server automatically, you approve the request in the browser, and the agent receives a token. The approval screen names the client that is asking, so you can tell what you are authorizing before you grant it. Dynamic client registration is supported, so most clients need no manual setup.
• Personal access tokens — a bearer token you create yourself, useful for scripts and non-interactive clients. Create one from your access-token settings.

Tokens are scoped. You grant an agent read or write access per resource category — catalog entities, teams, schema — and can even scope a token to specific entities. Grant the narrowest access that does the job; a read-only token is enough for an agent that only needs context. An agent only sees the tools its grant allows, so a read-only agent is not offered the editing tools at all.

Agent authorizations last 30 days. When one expires the client asks you to approve it again; nothing else changes.

What an agent can do

Once connected, an agent has tools to:

• Search and browse the catalog — find entities, list them by kind or owner, and read a single entity’s full detail.
• Traverse relationships — follow dependencies and run impact analysis to see what a change affects.
• Read documentation — retrieve an entity’s Markdown sections and its activity log to answer questions with organizational grounding.
• Inspect interfaces — read API specs, package coordinates, and other connectivity details to generate clients or integration tests.
• Check scorecards — list the standards your organization has defined, read an entity’s current score and per-rule pass/fail breakdown (with a failure message and remediation link for anything failing), and list which entities are failing a given scorecard or rule. Read-only: an agent cannot create, edit, or evaluate a scorecard — fixing a failing rule means editing the entity itself, which the editing tools already cover.
• Make changes — with write access, create and update entities, relationships, interfaces, and documentation.
• Read Componecat’s own documentation — list and read these pages to learn how the platform works, so the agent can walk you through setting up an integration or writing a descriptor file instead of guessing at it.

An agent can also browse the catalog as MCP resources: each entity is readable as its componecat.yaml descriptor, and a kind’s entities can be listed without knowing your taxonomy in advance.

Typical workflows

• Grounded code generation — before generating code for a service, the agent looks up its kind, languages, interfaces, and conventions.
• Cross-service integration — the agent follows depends-on edges, reads the target’s interface spec, and writes a correct client.
• Ownership resolution — the agent finds the owning team to route a review or an escalation.
• Documentation-grounded answers — the agent retrieves runbooks and architecture notes to answer a developer’s question with your context, not generic guesswork.
• Guided setup — the agent reads Componecat’s own documentation to talk you through connecting a provider or cataloguing a repository, step by step.
• Standards triage — before starting on a service, the agent checks its scorecard results and works through the failing rules first, or lists every entity still failing a standard to plan a cleanup pass.

Related

• Interfaces — what agents read to integrate.
• Relationships — the graph agents traverse.
• APIs — the REST surface alongside MCP.