Developers and AI agents
Connect publishes four machine interfaces: an MCP server at /mcp, an A2A agent at /a2a with a card under /.well-known/, a read-only HTTP API under /api/public/, and generated OpenAPI, Arazzo and AsyncAPI descriptions. All four read the same published documentation corpus. None of them reaches a workspace, and none of them writes.
The four doors#
They differ in who is calling, not in what they can see. An MCP client is a model host that wants tools; an A2A caller is another agent that found Connect from a well-known URI; the HTTP API is for a program that would rather issue a GET than negotiate a protocol; the descriptions are for a code generator or a workflow runner. Behind all of them sits one module, public_docs, so two doors cannot give two answers to the same question.
| Interface | Where | Speaks | Credential |
|---|---|---|---|
| MCP server | POST /mcp | JSON-RPC 2.0 over Streamable HTTP, revision 2026-07-28 | None |
| A2A agent | POST /a2a | JSON-RPC 2.0, A2A 1.0.0 | None |
| Public HTTP API | GET /api/public/docs/… | JSON over HTTPS | None |
| Descriptions | /developers/openapi.yaml, /developers/workflows.arazzo.yaml, /developers/asyncapi.yaml | OpenAPI 3.1.0, Arazzo 1.1.0, AsyncAPI 3.1.0 | None |
| Static manifests | /llms.txt, /docs-manifest.json, /docs-data/*.json, /.well-known/agent-card.json | Plain text and JSON | None |
Choosing one#
- You are building on a model host
- Use MCP. The connector gives ten read-only tools and four resources, and the tool descriptions tell the model to check capability status before claiming anything.
- You are building an agent that talks to other agents
- Use A2A. Fetch the Agent Card first; it names five skills and declares
streaming: false, so a caller knows not to open a stream. - You are writing ordinary client code
- Use the public API. Five GET endpoints, JSON in, JSON out, no handshake.
- You are generating a client
- Start from the OpenAPI description. It is an allowlist, not an export of the application.
- You want the order of a multi-step task
- Read the Arazzo workflows, which encode three sequences over the same API.
What none of them do#
Everything published is read-only and documentation-only. There is no public write endpoint on any of these interfaces, no tool that reaches a workspace's mail, calls, people or files, and no query language that could be pointed at the database. The application's own OpenAPI document, /docs and /redoc, is closed and stays closed; a route becomes public only by being written into the public description *and* listed in the generator's allowlist, so opening an internal endpoint cannot publish it by accident.
That is also why none of them asks for a credential. There is nothing behind these doors that a credential would protect: they serve the same generated files an anonymous visitor already receives from the website. Workspace access needs a signed-in session, which means a person and Google sign-in, not an API token.
The corpus underneath#
Each page in the public documentation carries a stable id such as C0142, a canonical URL, a one-paragraph summary, a capability status and a Markdown twin generated from the same source as the HTML. Every interface above returns those same fields. The status word matters more than anything else you will read through these APIs: available, available_owner, foundation, not_yet and reference are the whole vocabulary, and foundation means code exists while the usable feature is deliberately narrower.
Search results are ranked, not paginated. Titles are weighted above descriptions, page bodies are indexed at weight zero so a phrase that appears only in prose can still find its page, and the index rebuilds itself when the manifest's modification time changes — so a deploy that ships new pages is picked up without a restart.
Everything in this section#
39 pages, each with its own status and the date it was last checked against the running system.
| Page | What it covers |
|---|---|
| Adding Connect to ChatGPT | Using the Connect MCP server from ChatGPT: the endpoint, what it does and does not offer a connector, and the limits worth knowing first. |
| Adding Connect to Claude | Add Connect to Claude as a custom connector: the URL to paste, why no credential is asked for, and what the first connection should show. |
| API authentication | The public Connect API takes no credential and none exists to request. What that means, where workspace access actually lives, and what integration keys are not. |
| API error shapes | The error envelope the public API returns, the codes inside it, the one response that does not use it, and what a client should do with each. |
| API rate limits | The three request limits Connect enforces, the headers it does not send, and the client behaviour that keeps you under them. |
| API versioning | How Connect versions its published interfaces: the product version on the descriptions, protocol revisions negotiated per call, and what a client should not pin to. |
| Authenticating to the MCP server | The Connect MCP server accepts no credential and issues none. What the Origin check does instead, and why there is nothing to revoke. |
| Building an agent on Connect safely | The discipline an agent built on Connect should keep, and the controls Connect enforces regardless of whether the agent keeps it. |
| Crawler policy | Which crawlers this site allows, which decision is left open and why, and the trade-off behind naming model-training crawlers without blocking them. |
| Designing a resilient client | Every failure the public surfaces produce, sorted into transient and final, plus the backoff that suits a rate limit with no Retry-After header. |
| Getting help as a developer | What a developer report needs to be answerable on the first reply, what must be redacted from it, and which routes to the operator are actually published. |
| Idempotency in the API | Connect accepts no idempotency key, and does not need one: every published operation is a read. What that means for retries, and where the guarantee stops. |
| Integration keys | The cbj_ machine credential: how one is issued and scoped, why the plaintext appears once, how revocation works, and what it does not open. |
| Interoperating over A2A | Calling Connect as an A2A agent: the endpoint, the one method it answers, how a skill is chosen, and the operations it refuses. |
| llms.txt on this site | The two llms files this site publishes, what each contains, what is kept out of them, and why neither replaces robots.txt or a sitemap. |
| Markdown alternates | Every page has a Markdown twin at the same URL plus index.md: how to build the URL, what the body contains, and which one is canonical. |
| MCP error shapes | Every error the Connect MCP endpoint can return: the JSON-RPC code, the HTTP status beside it, what caused it, and what a client should do next. |
| Outbound webhooks | The published contract for events Connect delivers to a subscriber: the retry model, the de-duplication rule, and the honest status of delivery itself. |
| Pagination | Connect's API has no cursor and no page token. What limit really does, how results are ordered, and the two correct ways to read the whole corpus. |
| Public MCP tools | The ten read-only MCP tools Connect publishes, their input schemas, what each returns, and the four resources and two prompts alongside them. |
| Searching the documentation programmatically | GET /api/public/docs/search: the parameters, the response record, the ranking model, and the four sibling routes on the same public prefix. |
| Stable identifiers | Page ids, prefixed object ids, delivery identifiers and canonical URLs: which are stable, which change on purpose, and which must never be parsed. |
| Testing against Connect safely | There is no published sandbox environment. What you can exercise safely without one, what you cannot, and how to build the tests that matter locally. |
| The Arazzo workflows | Connect's Arazzo 1.1.0 document: three ordered sequences over the public API, what each produces, and how to run one by hand or with a runner. |
| The AsyncAPI description | The AsyncAPI 3.1.0 document at /developers/asyncapi.yaml: one outbound channel, one signed envelope, six event types, and what it deliberately leaves out. |
| The changelog and its feed | The changelog page, its Atom feed at /changelog/feed.xml, the fields in an entry, and the two quirks a feed reader should know about. |
| The Connect Agent Card | Connect's A2A Agent Card: where it lives, every field it carries, the five skills it advertises, and the fields that declare what is absent. |
| The Connect MCP server | The Connect MCP endpoint: its URL, the 2026-07-28 protocol revision, the Streamable HTTP transport, and exactly what is public. |
| The machine-readable documentation | Every generated JSON manifest on the site: docs-manifest.json, the docs-data files, what each field means and when they change. |
| The OpenAPI description | Where Connect's OpenAPI document lives, what it covers, the schemas it defines, and the allowlist that decides which routes can ever appear in it. |
| The product status manifest | status.json: the five-word capability vocabulary, the per-capability status and evidence, and how to depend on it without hardcoding a list. |
| The public API | Connect's public HTTP API: five read-only endpoints over the documentation corpus, their parameters, and the boundary that keeps workspace data out. |
| The public data model | The five object shapes a developer actually receives from Connect, field by field, and the product records that are deliberately not among them. |
| Time in the API | Every timestamp Connect publishes, in which format, in which zone, and the single place where a business's local time is the one that matters. |
| Using Connect from any MCP client | The protocol-level steps for talking to the Connect MCP server from any client: the methods, the request shapes, and a call you can paste into curl. |
| Verifying a bot is who it claims | A user agent string is a claim, not an identity. The two verification mechanisms, each vendor's own published address source, and what Connect does with them. |
| Verifying a Connect webhook signature | The exact HMAC computation behind X-Connect-Signature, worked in Python, Node and Go, and the four mistakes that make a verifier look correct. |
| Webhooks or polling | The trade-off between being told and asking, what each costs in requests and operational surface, and which one is actually available here. |
| Workspace MCP tools | There is no authenticated MCP tool in Connect. What that means, what is written down about the gates a workspace tool would pass, and what to use instead. |
Questions#
Is there an API key for any of this?
No. Every interface described here is unauthenticated because everything it returns is already public. Integration keys exist inside Connect for a different purpose and are not part of these surfaces — see Integration keys.
Which interface is the most complete?
They are equal by construction. Every one of them calls the same search, fetch, listing and status functions, so a page reachable through one is reachable through all of them, with the same fields and the same status.
Can I be notified when the documentation changes?
The corpus is regenerated on a deploy and each page carries an updated date you can compare. There is no subscription mechanism on these interfaces; the changelog and its feed is the published record of user-visible change.