# Developers and AI agents

Connect publishes a remote MCP server at `/mcp`, an A2A agent at `/a2a`, a read-only public HTTP documentation API and generated OpenAPI, Arazzo and AsyncAPI descriptions. Public documentation remains anonymous. The MCP server additionally exposes OAuth-authenticated tools bound to one authorized Connect workspace and business.

- **Status:** Available
- **Audience:** developer
- **Last verified:** 2026-09-30
- **Canonical:** https://connectbyjbrh.com/developers/

## Choose the surface

| Interface | Where | Private business access |
|---|---|---|
| MCP | `POST /mcp` | Yes — OAuth 2.1 + PKCE, scope and business bound |
| A2A | `POST /a2a` | No — published agent card remains public documentation |
| Public HTTP API | `GET /api/public/docs/...` | No — public documentation only |
| Generated descriptions | `/developers/*.yaml` | No — public protocol descriptions |

The MCP endpoint intentionally combines an anonymous documentation surface with a separately authorized business surface. A public tool never becomes private because a token is attached, and a private tool never runs without its required scope and business binding.

## Security boundary

- Private MCP tools derive workspace and business from the credential or OAuth grant rather than model arguments.
- Business record searches reuse Data Workspace business-reach rules and fail closed when a record type has no business rule.
- Writes call existing Connect domain services; the MCP server exposes no SQL tool and no arbitrary internal-route proxy.
- Owner diagnostics are excluded from the production marketplace registry.

## What authorization changes, and what it does not

A private MCP grant is deliberately narrower than a signed-in browser session. The authorization server records the user, workspace, requested scopes and one selected business. Tool arguments do not contain a workspace selector or a business selector that can replace those values. A model therefore cannot turn a tool for Business A into a query for Business B by inventing an identifier. The domain service still checks the business when the call runs, so a business that was later archived or removed does not remain reachable because an access token still exists.

**Public documentation** — Anonymous and read-only. These tools answer how Connect works from the generated documentation corpus.
**Business read** — OAuth scope `mcp:business:read`. It exposes the business profile, readiness, follow-ups, memory and business-reached customer-operation records.
**Business write** — OAuth scope `mcp:business:write`. It exposes supported configuration and customer-operation state changes through existing Connect services.
**Diagnostics** — Not a marketplace authority level. Owner test tools are removed from the production registry and can only be explicitly enabled on a non-production process.

## What a marketplace package can and cannot change

The manifests under the marketplace package are descriptions of this server, not a second implementation. ChatGPT, Codex, Claude, Cursor, Gemini CLI and an MCP Registry entry all point to the same HTTPS endpoint. A package can help a host discover skills and start OAuth, but it cannot grant itself a broader scope, bypass a held approval, or make a tool exist that the running server does not publish. That is why the package version and the deployed server contract have to be released together.

The first useful production test is therefore not whether a ZIP imports. Enumerate tools from the deployed endpoint, request a protected read, complete OAuth, confirm the returned business, then exercise one bounded write and one refusal. A package that installs while its remote server is still on an older contract is not a working release; it is only valid metadata pointing at the wrong runtime.

## 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](/developers/mcp-quickstart-chatgpt/) | Add Connect by JBRH to ChatGPT using the production remote MCP endpoint and OAuth. |
| [Adding Connect to Claude](/developers/mcp-quickstart-claude/) | Add Connect by JBRH to Claude using the standards-based remote MCP endpoint and delegated OAuth. |
| [API authentication](/developers/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](/developers/api-errors/) | 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](/developers/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](/developers/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](/developers/mcp-authentication/) | OAuth authentication for protected Connect MCP tools and the anonymous boundary for public documentation tools. |
| [Building an agent on Connect safely](/developers/agent-safety/) | The discipline an agent built on Connect should keep, and the controls Connect enforces regardless of whether the agent keeps it. |
| [Crawler policy](/developers/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](/developers/errors-and-retries/) | 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](/developers/developer-support/) | 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](/developers/api-idempotency/) | 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](/developers/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](/developers/a2a-integration/) | 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](/developers/llms-txt-here/) | 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](/developers/markdown-mirrors/) | 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](/developers/mcp-errors/) | 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](/developers/webhooks-outbound/) | 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](/developers/api-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](/developers/mcp-public-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](/developers/docs-search-api/) | 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](/developers/entity-ids/) | 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](/developers/sandbox/) | 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](/developers/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](/developers/asyncapi-events/) | 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](/developers/changelog-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](/developers/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](/developers/mcp-server/) | The production Connect MCP endpoint, protocol, public documentation tools and OAuth-bound business tools. |
| [The machine-readable documentation](/developers/machine-manifests/) | 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](/developers/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](/developers/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](/developers/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](/developers/data-model-public/) | 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](/developers/time-and-timezones/) | 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](/developers/mcp-client-generic/) | 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](/developers/bot-verification/) | 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](/developers/webhook-signatures/) | 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](/developers/webhooks-vs-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](/developers/mcp-workspace-tools/) | Authenticated MCP tools for one exact Connect business, including business data reads and controlled configuration writes. |

## Questions

### Which interface should an AI host use?

Use MCP. It is the only published machine surface that can obtain delegated private business access.

### Are A2A and the public HTTP API private APIs?

No. They remain documentation surfaces.

### Does the marketplace package contain credentials?

No. It points to the remote MCP endpoint; the host performs OAuth when protected tools are needed.

## Related

- [The Connect MCP server](https://connectbyjbrh.com/developers/mcp-server/)
- [Authenticating to the MCP server](https://connectbyjbrh.com/developers/mcp-authentication/)
- [Workspace MCP tools](https://connectbyjbrh.com/developers/mcp-workspace-tools/)
- [The public API](https://connectbyjbrh.com/developers/public-api/)

## What this page is based on

- `backend/app/mcp_server.py`
- `backend/app/mcp_oauth.py`
- `backend/app/public_developer_api.py`
- `backend/app/a2a_server.py`