Agent Connectors

Business connectors for Agents — GitHub, Google Workspace, Feishu and Notion — exposed as MCP tools, with credentials and authorization kept outside the Agent's environment.

Agent (sandbox) ──MCP + short-lived caller token──▶ Agent Connectors ──▶ Feishu / mail / …
                                                     ▲  holds OAuth credentials (encrypted)
Router ──service token: list/inspect operations──────┤
Owner's trusted device ─▶ Router ─approval grant─────┘

• ConnectorService credentials never enter the sandbox. Google API and remote MCP OAuth tokens use AES-256-GCM envelope encryption with Google Cloud KMS in the production configuration. Application configuration and Feishu CLI files use an encrypted file bundle, restored into a private memory-backed directory. This describes the configured service, not evidence that KMS has been provisioned on a particular deployment.

• Server-side authorization. Each call carries a Router-signed caller token for one Agent, one owner and a list of connections. A connection is usable only by its owner.

• Reads run, writes wait. Tools declare read or write. A write returns approval_required with an operation ID; it runs only after Router presents the exact operation to the owner and posts an approval grant bound to the operation's digest. Grants are single use and short-lived. Passing --yes or similar from the model has no effect.

• Owner operation policy. Each connection lists its operations (for example Gmail: read messages, send, trash). The owner sets each one to allow (runs directly, writes included), ask (approval for every call, reads included) or deny (not offered to the Agent and refused). Defaults: reads allow, writes ask. Read-only callers never write and cannot use ask operations. See Security model.

• Narrow pre-approval. A connection can pre-approve a write tool for exact argument values (for example, appending to one invoice table).

• Uncertain outcomes are not retried. An unexpected failure during a write is recorded as uncertain.

Start with the four-service setup guide. See also security and Router integration.

Components

Channels (receiving and replying to Feishu or mail messages) stay in Router. Business tools (calendar, documents, mailbox, reimbursement) belong here.

Related MCP server: foral

Usage

npm install
npm test
agent-connectors init-key state/sealing.key
agent-connectors keygen --kid caller-2026-10 --out keys/caller        # private key goes to Router
agent-connectors keygen --kid authority-2026-10 --out keys/authority  # private key goes to Router's approval path
agent-connectors serve --config connectors.json

{
  "listen": { "host": "127.0.0.1", "port": 18100 },
  "stateDirectory": "state",
  "encryption": { "provider": "development-file", "keyFile": "state/sealing.key" },
  "trust": {
    "issuer": "https://router.example",
    "callerKeys": "keys/caller/public.jwks.json",
    "authorityKeys": "keys/authority/public.jwks.json"
  },
  "connections": [
    {
      "id": "work-feishu", "kind": "feishu", "owner": "@alice:router.example",
      "settings": { "directory": "state/feishu" }
    }
  ]
}

Feishu uses the official CLI's private account directory inside the configured secret file store. For GitHub, Google and Notion, use agent-connectors connection connect <id> --config connectors.json --authority-key keys/authority/private.jwk.json. Use agent-connectors init --out <new-directory> --owner <owner-id> to generate a complete four-service configuration. The generic credential set command is for custom connectors; it is refused for the three OAuth connectors.

The example and init use a development key and must bind to loopback. Production uses encryption.provider: "google-cloud-kms" with a key resource name and a projected workload identity token; see the encryption configuration.

Programmatic use: startConfigured(file) starts the built-in connectors with the same encrypted application-file lifecycle as the CLI. start(loadConfig(file), connectors) accepts custom connectors. Token issuance is available from @olorinm/agent-connectors/issuer.

@olorinm/agent-connectors/read-client provides ConnectorReadClient for a trusted product server. It uses the official MCP SDK and short-lived, signed readOnly caller tokens. The service refuses writes for these tokens even when a connection has pre-approval rules. The composing product must bind every call to its authenticated owner, Agent and assigned connections; the browser and Agent receive neither the signing key nor tokens.

An explicit cloudflare-worker-secrets encryption option is also available; see remote key wrapping. This uses a separate Worker deployment and is not non-exportable KMS.

Connectors

• Feishu: the official lark-cli as the owner; the CLI's own risk declaration decides read vs write.

• Google: formal Google APIs through official Node SDKs, for personal and Workspace accounts. Gmail tools match the names, inputs and result fields of Google's Gmail MCP server and return shaped messages, not raw API payloads. No MCP preview eligibility is needed; the local Agent interface remains MCP.

• GitHub and Notion: official remote MCP, operator-owned OAuth configuration or dynamic registration, typed tool discovery and locally reviewed read/write policy.

Status

A public read adapter can also be composed into a trusted product server:

• @olorinm/agent-connectors/feishu-bot-reader: FeishuBotReader runs the pinned official CLI using a fixed bot identity. Help, schemas and skills use an unconfigured CLI. Actual commands require both a read risk declaration and a read-only dry-run plan. Writes, identity changes and host file paths are refused.

This adapter is not a deployment of ConnectorService: it reuses server-side credential files and does not provide KMS encryption, user OAuth, approval execution or caller-token verification. The composing server must authorize the Agent, owner and conversation before invoking it. Agent environments receive tool results, never the credential files. Other credentials, including model access, are outside this guarantee.

0.1.0-alpha.2: four connector kinds, OAuth lifecycle and approval-bound tools. Real accounts still require operator setup and owner consent. Mau/Router's connection UI, token delivery and approval presentation remain integration work.

Cloudflare read broker

The Cloudflare deployment is a separate, narrow read broker. It uses Worker secrets for its fixed upstream credentials and does not need KMS. It supports the Feishu bot reader; it does not deploy the general OAuth connection store or the approval-bound write service described above.