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 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

Any client that supports remote MCP servers takes the endpoint URL directly, with sign-in completing in your browser.

Self-hosted instances: point any of the above at your own host’s /api/mcp.

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, wiki — 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.

An agent’s token is short-lived and its client renews it in the background, so a connected agent keeps working without you approving it again. An authorization that goes 30 days without being renewed expires, and the client asks you to approve it once more; nothing else changes. A client that does not renew tokens asks you hourly instead.

Organization admins see every member’s access tokens and the agents they have authorized in Organization settings → Access Tokens, where an “Issued to” column names the app each authorization was granted to, and can revoke any of them.

What an agent can do

Tool results include a full link to each entity, team, scorecard and wiki page they mention, and a list of links for any references in documentation or wiki content, so an agent can point you at the right page in Componecat.

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. search_catalog takes the full query language, including a semantic clause (~"...") that ranks by meaning alongside field clauses.
• Start from a description — when your organization has an embedding model, an agent can look things up the way you describe them. find_relevant_entities takes a phrase like “the service that sends invoices”, plus an optional filter in the query language (kind:component lifecycle:production), and returns the best-matching entities, each with a short snippet saying why it matched. find_relevant_documentation does the same for documentation sections — across the catalog, or within one entity — and names the entity each section documents, returning only sections of entities the agent’s token is allowed to read. Each result has a relevance score: how close the match is in meaning, used to rank results. It is not a confidence that the match is the right one, so agents are told to confirm a match before relying on it. Agents use these tools to pick the starting point, then follow relationships from there. Without an embedding model the two tools are not offered at all, and agents use search_catalog; they appear as soon as an admin adds one (see Turning on search by meaning). global_search, which searches entities, wiki pages and this documentation in one call, also matches entities by meaning when given a description of three or more words.
• Traverse relationships — follow dependencies and run impact analysis to see what a change affects. get_impact_analysis follows every relationship kind your organization marks as a dependency kind unless the agent names specific ones with kindKeys, and walks downstream (the default), upstream (what depends on the entity) or both via direction, up to maxDepth hops. Each entity it returns comes with its hop count and the relationship kinds it was reached by. The older single kindKey parameter still works and is added to kindKeys. traverse_graph returns everything around an entity — across any mix of relationship kinds, in either direction, up to a depth (default 5) — in one call, and find_paths answers how two entities are connected, shortest path first. Every edge carries where it came from (entered by hand, declared in a descriptor, or inferred) and its confidence, and a truncated flag says when a very large graph was cut short.
• Read documentation — retrieve an entity’s Markdown sections and its activity log to answer questions with organizational grounding.
• Hand work between teams — for an organization admin, reassign_team_entities moves every entity a team owns, or a listed set of them, to another team in one step, for a reorganization or before deleting a team. It is all-or-nothing, and the token needs write access to both teams and to every entity it moves.
• Look into Catalog Intake — for an organization admin, list_catalog_intakes lists your catalog intakes with their status and repository counts, get_catalog_intake reads one intake’s scope, defaults, step progress and token usage, and list_catalog_intake_entities lists the components an intake created or linked, optionally only the created or only the linked ones, or those in one review state. These tools read and never change an intake (see Ask an AI agent about an intake).
• 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.
• Follow your wiki — list and read wiki pages, and look up the guides for a kind, field, team, collection, scorecard or entity with get_guides_for (written in the wiki’s reference syntax, e.g. $kind:service or @platform). Agents are told to read the guides for an entity’s kind before creating or editing one, so conventions you write down in the wiki are applied. With write access on the wiki category an agent can also create and edit pages; when the wiki is synced from git it is read-only, and the agent is told which repository file to edit instead.
• 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.
• Wiki — the guides agents read with get_guides_for.
• AI assistant — the same tools, in a chat panel inside the app.