Connectors

How Runtime Catalog toolkits, execution definitions, and connected accounts fit together.

Open Connector has one connectable catalog identity: a toolkit. A toolkit owns its authentication methods, endpoint configuration, metadata, and the tools an agent can call. There is no separate runtime provider or auth-provider layer.

Runtime Catalog model

Catalog object	Owns	Runtime representation
Toolkit definition	Name, discovery metadata, `authMethods`, optional connection fields, and trusted API endpoints.	One row in `runtime_toolkit_catalog`.
Tool definition	Agent-facing input/output schemas, scopes, tags, and lifecycle.	One row in `tool_catalog`.
ExecutionDefinition	Declarative HTTP or GraphQL request mapping, or a named custom executor.	JSONB on the tool row; loaded only when the tool executes.
Trigger type	Event schema plus a lazy transport key.	One row in `trigger_type_catalog`.
Connection	A user's encrypted credentials for a selected toolkit authentication method and project scope.	Stored independently from the catalog.

Compiled catalog artifacts are source controlled under packages/tool-registry/artifacts/<toolkit>/catalog.json or catalog.json.gz when the per-Toolkit release manifest marks compression: "gzip". The release manifest records the complete, verified set and artifact digest. The server reads only the PostgreSQL Runtime Catalog; it never falls back to static tool modules.

Authentication methods

Each toolkit contains an authMethods array. An entry has a namespaced id such as github.oauth2 and is either available or explicitly unavailable with a reason.

Kind	What the user supplies	What Open Connector does
`oauth2`	Browser consent, or client credentials when configured.	Builds the authorization URL, exchanges and refreshes tokens, then stores them encrypted.
`api_key`	A long-lived key or token.	Encrypts the supplied fields and injects them using the selected method's request template.
`basic`	Username/password or equivalent key/secret pair.	Encrypts both values and injects the configured request fields.

Endpoint defaults never contain credentials. Credential injection belongs to the selected authentication method, so an execution definition remains portable and can be published without secrets.

Artifact example

This abbreviated artifact defines a toolkit and one declarative HTTP tool. The same shape is used for OpenAPI and GraphQL declarations after compilation.

{
  "version": "v1",
  "toolkit": {
    "slug": "my-crm",
    "name": "My CRM",
    "authMethods": [{ "id": "my-crm.oauth2", "kind": "oauth2", "status": "available" }],
    "endpoints": {
      "api": { "baseUrl": "https://api.mycrm.com/v2", "allowedBaseUrls": [], "defaultHeaders": {} }
    }
  },
  "tools": [{
    "definition": { "slug": "MY_CRM_CONTACTS_LIST", "toolkit_slug": "my-crm", "name": "List contacts" },
    "executionDefinition": { "version": "v1", "kind": "http", "endpointKey": "api", "method": "GET", "path": "/contacts" }
  }],
  "triggerTypes": []
}

Publishing and using the deployed catalog

After changing a Toolkit's declarations, compile that Toolkit, assemble the catalog release, and publish it explicitly to the database used by the server:

pnpm tools:compile -- --toolkit my-crm
pnpm catalog:build
DATABASE_URL='postgres://…' pnpm tools:publish-catalog

Publication validates artifact digests and atomically projects the release into PostgreSQL. It is separate from server startup and from database migrations, so a running service never silently changes its executable catalog.

For an agent or integration, the normal sequence is:

Discover a toolkit and its supported authentication methods.
Create or choose an auth configuration for that toolkit and method.
Create a connection for the user and project scope.
Invoke a tool through that connection.

See API reference for the exact discovery and execution routes, and Connected accounts for the credential lifecycle.

Runtime Catalog model

Authentication methods

Artifact example

Publishing and using the deployed catalog

On this page