Docs
Home

Build a connector

Add an operator-owned OAuth connector to Monad Community Edition.

Monad Community Edition ships the connector framework without bundled provider implementations. Operators can add an OAuth-protected HTTP service without changing credential storage, authorization, agent-tool dispatch, or the settings UI.

Start with examples/connectors/example-http. The example contains four parts:

  1. A client that calls connectorFetch and validates every external response with Zod.
  2. A Connector descriptor containing OAuth endpoints, scopes, identity lookup, and agent tools.
  3. A catalog contribution that makes the connector visible in Settings.
  4. An EditionPlugin that registers the contribution before the server accepts traffic.

Copy the example to an operator-owned folder, replace its placeholder endpoints and schemas, then add the plugin to the plugins array in edition/current.ts. Restart Monad after changing the plugin manifest.

Security rules

  • Put OAuth client credentials into Monad through the connector setup UI. Never commit client secrets or access tokens.
  • Use connectorFetch for provider calls. It injects the resolved credential, refuses redirects, bounds retries, and parses the response schema.
  • Request the smallest practical OAuth scope set.
  • Mark tool annotations accurately, especially write/destructive behavior.
  • Parse tool arguments and provider responses; do not cast untrusted values.
  • Keep connector names, catalog slugs, contribution IDs, and runtime IDs unique.
  • Treat provider content as untrusted input in tool descriptions and system messages.

Monad handles authorization, encrypted credential persistence, PKCE, refresh, personal-versus-shared connection selection, usage logging, and per-tool disable controls. A connector remains responsible for provider-specific pagination, idempotency, rate-limit semantics, error envelopes, and response size limits.