# Switchboard

> Switchboard turns external JSON and XML HTTP APIs into MCP tools. An AI writes a mapping definition (a static request shape plus CEL expressions); Switchboard validates it, keeps every attempt as an immutable revision, and serves a mapping's last-good revision as a tool on POST /api/mcp. Every API call authenticates with EndPointBlank credentials in the Authorization header: an agent should connect through EndPointBlank (it signs in to EndPointBlank with OAuth, the user approves it there, and the agent gets Bearer tokens without ever seeing a secret; see https://app.endpointblank.com/docs/agent-sign-in); scripts and CI can send the client id and secret as HTTP Basic. EndPointBlank knows the user as the owner of their account by their Switchboard email address, so they sign in to EndPointBlank and approve the agent; on EndPointBlank's consent page they pick their own organization, not Switchboard's.

Read the overview, then definitions and expressions. Copy the worked example closest to the target API and adapt it; every example validates as active. Errors from POST/PATCH /mappings are a correction loop, not a failure: fix what each error code says and PATCH the complete definition again. A 503 validation_unavailable means nothing was saved; retry the identical request.

## Docs

- [Overview](/docs/index.md): what Switchboard is, the authoring workflow, a quick start
- [Authentication](/docs/authentication.md): connect through EndPointBlank (your account, protected resource metadata, the resource to ask for, what the user sees, a connector added at /mcp must be re-added at /api/mcp), or the client id and secret as HTTP Basic
- [EndPointBlank agent sign-in](https://app.endpointblank.com/docs/agent-sign-in): EndPointBlank's own guide to signing an agent in
- [Registration](/docs/registration.md): the one-time step every EndPointBlank environment needs before any authorized route works
- [Mapping definitions](/docs/definitions.md): every field and rule, body formats, path-hole rules, the XML always-list convention, limits
- [Expressions](/docs/expressions.md): CEL bindings (args, response, now), optional values, has(), map/filter, no int/double mixing, null means omit
- [Validation](/docs/validation.md): error codes, stages, the dry run, what actually gets served vs. the latest write, the correction loop with x-session-id, revision history
- [Runtime errors](/docs/errors.md): the four categories, every code, retryable, protocol errors
- [Credentials](/docs/credentials.md): API keys, auth_ref, rotation, deletion
- [Webhooks](/docs/webhooks.md): signature verification, filter/event_mapping expressions, deliveries, replay-dedup and its window
- [Events](/docs/events.md): reading stored webhook events and deliveries, reprocessing, redelivering, retention/purging
- [Targets](/docs/targets.md): the managed agents a webhook delivers to, validation codes, sessions, cost and rate limits, token health, dismissing orphaned vaults
- [Activity](/docs/activity.md): a live timeline and service map of everything recorded for a tenant, viewer links

## Examples

- [JSON GET with pruning](/docs/json_get_pruning.json): optional query parameters, null means omit, filter and map a large response
- [JSON POST with a body](/docs/json_post_body.json): body built from arguments, defaults, now, optional header
- [XML API response](/docs/xml_get_response.json): attributes, #text, always-list children, int() and double()
- [XML request body](/docs/xml_post_body.json): xml_root, attributes on the root element
- [Form-encoded POST](/docs/form_post.json): flat form body, including a field only when an argument is present
- [Error mapping](/docs/error_mapping.json): path parameter, error_mapping extracting the vendor's code, message and request id
- [Stripe payment webhook](/docs/stripe_payments.json): stripe preset, filter on event type, event_mapping pruning, a continue delivery keyed on the customer
- [GitHub push webhook](/docs/github_pushes.json): github preset, filter on header and default branch, event_mapping over a commit list
- [Managed agent config](/docs/billing_agent_agent.json): mcp_toolset tool wired to this Switchboard's /api/mcp with always_allow
- [Managed agent environment](/docs/billing_agent_environment.json): limited networking with allow_mcp_servers
- [A target tying them together](/docs/billing_agent_target.json): api_key_ref, caller_ref, rate_limit

## Schema

- [Mapping definition JSON Schema](/schema/mapping-definition.json): JSON Schema 2020-12, generated from the validator's own source
- [Webhook definition JSON Schema](/schema/webhook-definition.json): JSON Schema 2020-12, generated from the webhook validator's own source