Community Connectors

A community connector is a package-level integration descriptor: it projects agent-callable tools and triggers onto Smithers’ Tier 0 substrate, instead of adding a workflow node per app. The manifest is declarative, stating what tool and trigger surfaces exist, which auth grants they require, and which runtime adapter loads them. Runtime code may live in the package, but Smithers discovers it only through the loader contract below.

Package Layout

smithers-connector-acme/
  package.json
  smithers.connector.json
  openapi/acme.yaml
  mcp/server.json
  src/index.ts
  README.md

smithers.connector.json is the contract. package.json exposes the loader module as an ESM export, with a smithers.connector field pointing at the manifest:

{
  "name": "smithers-connector-acme",
  "type": "module",
  "exports": {
    ".": "./src/index.ts"
  },
  "smithers": {
    "connector": "./smithers.connector.json"
  }
}

Manifest Format

The manifest format id is smithers.connector.v1. Unknown top-level keys are ignored; unknown keys inside tools, triggers, auth, and surfaces must fail validation, so authors catch typos before an agent receives the tool catalog.

{
  "schema": "smithers.connector.v1",
  "id": "acme",
  "name": "Acme",
  "version": "0.1.0",
  "description": "Curated Acme tools for Smithers agents.",
  "loader": "./src/index.ts",
  "auth": {
    "oauth": {
      "provider": "acme",
      "grant": "authorization_code_pkce",
      "scopes": ["tickets:read", "tickets:write"],
      "tenantKey": "workspace_id"
    }
  },
  "surfaces": {
    "openapi": {
      "spec": "./openapi/acme.yaml",
      "baseUrl": "https://api.acme.example"
    },
    "mcp": {
      "command": "node",
      "args": ["./dist/mcp-server.js"]
    },
    "webhooks": {
      "provider": "acme",
      "signature": "hmac-sha256",
      "idempotencyKey": "$.event_id"
    }
  },
  "tools": [
    {
      "name": "acme_create_ticket",
      "surface": "openapi",
      "operationId": "createTicket",
      "description": "Create one Acme ticket after checking for an existing ticket with the same external id.",
      "auth": "oauth",
      "scopes": ["tickets:write"],
      "sideEffect": true,
      "idempotency": {
        "key": "externalId",
        "required": true
      }
    },
    {
      "name": "acme_search_tickets",
      "surface": "mcp",
      "tool": "search_tickets",
      "description": "Search Acme tickets by text, status, assignee, or customer.",
      "auth": "oauth",
      "scopes": ["tickets:read"],
      "sideEffect": false
    }
  ],
  "triggers": [
    {
      "name": "acme_ticket_updated",
      "surface": "webhook",
      "event": "ticket.updated",
      "auth": "oauth",
      "scopes": ["tickets:read"],
      "dedupe": {
        "key": "$.event_id"
      },
      "payloadSchema": {
        "type": "object",
        "required": ["ticketId"],
        "properties": {
          "ticketId": { "type": "string" }
        }
      }
    }
  ],
  "tokenBroker": {
    "audience": "acme",
    "defaultTtlSeconds": 300,
    "allowedActions": ["acme_create_ticket", "acme_search_tickets"]
  }
}

Loader Contract

A Smithers connector loader must:

validate the manifest before loading package code.
resolve auth via the OAuth plane and token broker, never by handing durable credentials to an LLM-visible tool call.
project tools from surfaces.openapi, surfaces.mcp, or the package loader into AI SDK-compatible tools.
register triggers from surfaces.webhooks with signature verification and dedupe before workflow dispatch.
enforce scopes for every tool and trigger invocation against the connected user and tenant.
Preserve idempotency metadata so retries and resumes avoid duplicate write-side effects.

Loader modules export one named loadConnector function:

export type SmithersConnectorContext = {
  manifest: unknown;
  connection: {
    userId: string;
    tenantId?: string;
    scopes: string[];
  };
  tokenBroker: {
    issue(input: {
      audience: string;
      scopes: string[];
      action: string;
      ttlSeconds?: number;
    }): Promise<{ token: string; expiresAt: string }>;
  };
};

export async function loadConnector(ctx: SmithersConnectorContext) {
  return {
    tools: {},
    triggers: [],
  };
}

The loader may add custom tools that OpenAPI or MCP can’t represent, but they still need manifest entries: the manifest is the auditable catalog Smithers shows to agents and humans.

Tool Declarations

Each tool declaration describes one agent-callable capability, distinct from a raw endpoint. Keep the surface small and curated, with clear names and task-shaped descriptions. Required fields:

Field	Purpose
`name`	Stable tool name exposed to the agent. Prefix with the connector id.
`surface`	`openapi`, `mcp`, or `custom`.
`description`	Agent-facing behavior, limits, and recovery guidance.
`auth`	Auth profile key, or `none` for public tools.
`scopes`	Minimum delegated scopes this action requires.
`sideEffect`	`true` for writes, sends, charges, deletes, or external state changes.

OpenAPI tools bind via operationId, MCP tools via the upstream MCP tool name, custom tools to code returned by loadConnector. Side-effecting tools must declare idempotency.required: true unless the upstream provider already supplies an idempotency key, request id, or natural unique key.

Trigger Declarations

Triggers describe external events that start or resume workflows: not workflow nodes, and shouldn’t grow into a provider-specific palette. Required fields:

Field	Purpose
`name`	Stable trigger id exposed to workflow authors.
`surface`	`webhook`, `poll`, or `mcp`.
`event`	Provider event name or polling resource.
`auth`	Auth profile key required to subscribe or poll.
`dedupe.key`	JSONPath or provider event id used for idempotent dispatch.

Webhook triggers declare the provider signature scheme and payload mapper through surfaces.webhooks; poll triggers declare interval bounds and cursor storage requirements in the manifest before registration.

Auth Requirements

Connector auth declarations are requirements, not secrets: the OAuth plane owns authorization-code + PKCE flows, encrypted refresh-token storage, single-flight refresh, and per-user/per-tenant scoping. Supported auth profiles:

Profile	Use
`oauth`	Delegated per-user OAuth through the Smithers OAuth plane.
`apiKey`	User-supplied key stored in the credential vault, exposed only via the token broker.
`none`	Public or local-only tools.

Never put tokens, client secrets, refresh tokens, service-account credentials, or shared bot tokens in a connector package. Runtime calls receive scoped action tokens from the tokenBroker; the broker exchanges or unwraps provider credentials outside the agent transcript.

Tier 0 Integration Points

Community connectors plug into these universal surfaces:

Tier 0 surface	Connector field	Loader behavior
OAuth plane	`auth.oauth`	Resolve delegated user consent, tenant key, scopes, and refresh lifecycle.
Scoped token broker	`tokenBroker` and per-tool `scopes`	Issue short-lived, revocable, auditable action tokens the LLM never sees.
OpenAPI tools	`surfaces.openapi` + `tools[].operationId`	Build curated tools with `createOpenApiTools`; never dump every endpoint by default.
MCP client	`surfaces.mcp` + `tools[].tool`	Pass selected MCP tools through with names and descriptions from the manifest.
Webhook ingress	`surfaces.webhooks` + `triggers[]`	Verify signatures, map payloads, dedupe events, and dispatch workflows.
Generic HTTP / sandbox	`surface: "custom"`	Run package code for cases OpenAPI/MCP can’t express.

Anti-Patterns

Don’t add a node per app: connectors contribute agent tools and triggers, not a giant fixed-schema workflow palette.
Don’t publish every OpenAPI operation as a tool: collapse noisy endpoint sets into task-shaped actions.
Don’t bypass delegated OAuth with service-account or shared-bot tokens.
Don’t refresh tokens independently per tool call; route refresh through the single-flight OAuth/token broker path.
Don’t omit idempotency from write tools or webhook triggers.
Don’t hide tool behavior in package code when the manifest can declare it.

Review Checklist

Before accepting a community connector, verify:

The manifest validates as smithers.connector.v1.
Every tool has a clear description, auth profile, scope list, and side-effect marker.
Every write tool has idempotency metadata.
Every trigger has signature verification or polling cursor rules plus dedupe.
OAuth scopes are the minimum needed for the declared tools and triggers.
The package uses OpenAPI, MCP, webhook ingress, or the token broker instead of inventing a parallel integration plane.

Start

Articles

Learn

Capabilities

Build Workflows

Run and Operate

Workflow Pack

Components

Integrations

Agent Support

Examples

Contributing

Community Connectors

Package Layout

Manifest Format

Loader Contract

Tool Declarations

Trigger Declarations

Auth Requirements

Tier 0 Integration Points

Anti-Patterns

Review Checklist

​Package Layout

​Manifest Format

​Loader Contract

​Tool Declarations

​Trigger Declarations

​Auth Requirements

​Tier 0 Integration Points

​Anti-Patterns

​Review Checklist

Package Layout

Manifest Format

Loader Contract

Tool Declarations

Trigger Declarations

Auth Requirements

Tier 0 Integration Points

Anti-Patterns

Review Checklist