Topology Index

npx add-mcp 'https://topologyindex.com/mcp'

---

schema: formation.doc/v0.1 kind: doc visibility: public canonical_url: https://topologyindex.com/docs/api/integration.md description: 'How an AI agent finds a multi-agent topology on Topology Index over HTTP or the public MCP endpoint, uses a starter formation and reports outcomes.' path: /docs/api/integration.md product_api_version: v1 schema_version: v0.1 title: 'Integration guide for agents'

Integration guide for agents

Use this when you are an agent deciding how to organize work across one or more LLM agents, or a developer wiring an agent to this service. Every URL returns raw Markdown with YAML frontmatter; read the frontmatter for identifiers and paths, and the prose for explanation.

Choose a topology without an account

• Pick a starting pattern by the shape of the task from the decision guide: the table in /llms.txt, or the choosing frontmatter of /patterns/index.md. If you know the kind of work but not its shape, a task domain page such as /domains/security.md lists the shapes common in it and the published findings tagged with it; every domain is at /domains/index.md.
• Read the pattern page for its failure modes and sources, and compare it against a strong single-agent baseline: /patterns/single_agent.md.
• Copy a starter from /starters/index.md whose task_classes and patterns match (?task_class=coding.bugfix keeps only the starters declaring that class). Starters are unvalidated: nobody has run them here.
• /llms.txt lists every public page in one request.

Connect over MCP without an account

https://topologyindex.com/mcp is a public, stateless remote MCP server over Streamable HTTP. It needs no credential and keeps no session: send JSON-RPC with POST; GET and DELETE answer 405. Its read-only tools are search (keyword search over patterns, aliases, families, task domains, the decision guide, published findings, research, starters and guides; a search that matches nothing answers with the decision guide), fetch (any public page by path or URL), list_patterns (the decision guide, one family, or one task domain page), get_pattern (by identifier or alias) and list_starters (optionally for one task class), and every page in /sitemap.txt is also an MCP resource. Every page it returns is the same Markdown document the HTTP route returns; list_patterns without a family or domain and a search without a match return the same rows as the choosing frontmatter of /patterns/index.md. Start with list_patterns or search. The one write, report_outcome, accepts a ticket from a content-bearing content read and a short worked, partly or did_not_work answer; pattern and starter redemptions return indexed follow-up material when available. See the limited rollout below.

Claude Code:

claude mcp add --transport http topology-index https://topologyindex.com/mcp

Any client that reads an mcpServers configuration:

{
  "mcpServers": {
    "topology-index": {
      "type": "http",
      "url": "https://topologyindex.com/mcp"
    }
  }
}

Recommendations, evaluations and every private read are not on this endpoint; they need a credential and the local bridge below.

Register, evaluate and report with a credential

• Credentials are issued by the operator; see authentication.
• Register a formation privately, run it with the formation CLI runner, and read the resulting evidence and decisions; every route is listed in routes.
• The CLI also exposes these operations to an agent over a local MCP stdio bridge (formation mcp --stdio).

Reporting outcomes (limited rollout): if your pattern, starter or formation read includes a Use-Ticket or "Report back" note, keep it with your task. Once you have applied it and know the outcome, report worked, partly or did_not_work using the supplied call; no account or API key is needed. Get a verification checklist or an alternative to try. Reads without a ticket have nothing to report.

What this service will not tell you

It does not rank patterns or claim that one arrangement beats another in general. A result here is about one complete configuration on one workload, and none is public yet.