Integrations
Integrations connect an Organization to external systems. A Connector is the definition of one system in Vocal's catalog; a Connection is one Organization's authorized link to it, or to a third-party MCP server. Agents call the tools of a Connection through Tool bindings, Triggers bring the system's events in, and every execution is recorded as a Run.
On the Phase 0 host. The api serves the operations on this page since contracts 1.60.0 (deploy #70). The integrations service that executes them is not deployed there yet, so no bound tool, Trigger or OAuth callback runs on the host; the routes and shapes below are served, and the behaviour that needs the service is not yet observable.
The catalog
GET /v1/connectors lists every Connector with its status. A planned Connector is designed and not built, and cannot be connected; the catalog is the same for every Organization.
Connections
| Step | Operation |
|---|---|
Create a Connection to a Connector; it starts pending_authorization | POST /v1/connections |
| Authorize an OAuth Connection: answers the vendor's authorization URL for the Member's browser | POST /v1/connections/{connection_id}/authorize |
| Enter a key, token or certificate instead; it is sealed and never answered | PUT /v1/connections/{connection_id}/credentials |
| Revoke the Connection; revoked is final | DELETE /v1/connections/{connection_id} |
Authorizing is Session only, by an owner or admin. The authorization uses PKCE and a single-use state, and asks only for the scopes of the Connection's enabled tools.
Tool bindings and MCP servers
A Tool binding grants an Agent named tools of a Connection, each with the name the model sees, its constraints and its deadline, pinned to the contract digest of the tool. A bound tool reaches the model as a Tool of type mcp.
POST /v1/mcp-servers registers a third-party MCP server and creates its Connection; the endpoint passes the egress guard. When a server changes a tool's definition, the tool is refused with schema_drift until you accept the new definition and publish a new Agent version that freezes it.
Triggers and Runs
A Trigger subscription acts on a Connection's events through a filter over the Trigger's data; its subscription_token is answered once. Setting the action start_call needs an owner or admin in a Member session. Trigger events are listed with identifiers only, and a replay runs an event's action again under its original id. GET /v1/runs lists the Runs of tool calls and Triggers.
Messages and notifications
POST /v1/messages is the send action: one message to one recipient through a send tool of a Connection. Since contracts 1.61.0, which the Phase 0 host serves since deploy #73, the route checks the recipient's consent first: it refuses an opted-out recipient with 422 contact_opted_out and otherwise queues the Message, or defers it in quiet hours. The integrations service that sends a queued Message is not deployed on the host, so nothing is sent there. Notification rules deliver record events to a notify tool of a Connection, with every argument but the text fixed.