Your agent gets a thousand tools. It never touches your keys.
OpenConnector is a switchboard you run yourself: connect an app account once, and any AI agent can act in GitHub, Gmail, Notion, Slack and 1,000+ other services through one plug — while every credential stays locked behind the board.
An independent explainer for oomol-lab's open-connector — built to take you from "never seen it" to "ready to implement".
01
Every agent integration starts with handing over a key
Why does this exist?
You built an agent that should file the issue, send the email, update the doc. The moment you let it, you face two bad options.
Option one: give the agent your keys. Paste API keys — the secret strings services issue for programmatic access — into the agent's environment. Now your GitHub token rides along in every prompt, every log line, every crash report: one verbose trace away from a leak. And an agent holding a raw key can do anything that key allows, not just what you meant.
Option two: build it properly, per service. The consent-redirect dance apps use to grant access (OAuth), token refresh, request schemas, permission scopes — GitHub alone is a weekend. Gmail, Notion, Slack, BigQuery… multiplied by everything your users already use, it's your whole roadmap.
The trade nobody likesHosted connector platforms solve this — by holding your users' credentials on someone else's cloud, behind someone else's bill and terms.
02
A switchboard between your agent and everything else
What does it actually do?
OpenConnector is a gateway you run yourself — an open-source alternative to Composio. Your agent plugs into one side; 1,000+ services are wired into the other.
Connect an account once — an API key or an app approval — and the gateway keeps that credential. From then on, any agent you authorize calls typed actions like github.get_current_user: over 10,000 of them, prebuilt, each with a strict input/output schema, its required permissions, and a plain-markdown guide an agent can read before calling.
Agents reach the board four ways — and humans get a web console to browse the catalog, connect accounts, and watch every run.
| Surface | Endpoint | Built for |
|---|---|---|
| the Model Context Protocol (MCP) — the standard socket agent apps use to discover and call tools | /mcp | agent hosts: 4 discovery tools, zero wiring |
| HTTP API | /v1/actions/* | scripts and custom clients |
| Connector SDK — a thin TypeScript client | npm package | your app's own code |
| Web console | http://localhost:3000 | humans: connect, inspect, debug |
03
The key never crosses the board
Why is it elegant?
The clever move isn't the catalog. It's the boundary.
Everything secret lives on one side of a line: stored credentials (encrypted at rest with a key only you hold), the token-refresh machinery, the raw provider secrets. What crosses the line is only what an agent needs: action names, schemas, a safe account label like acme-team, and results.
The agent can say "file this issue as acme-team". It cannot say "give me the token" — no endpoint returns one. That single boundary turns "my agent has my passwords" into "my agent has permissions I can watch and revoke": every call is checked against an allow/block policy, gated by a revocable runtime token, and logged with secrets redacted.
Agents get verbs, never keys — the credential has no route out of the gateway.
04
Inside the gateway
How is it built?
Six steps between 'agent asks' and 'issue filed' — and the key stays below the line the whole way.
The runtime is TypeScript on Hono (a small, fast web framework), and every provider is catalog source code: definition.ts declares auth types, credential fields and action schemas; executors.ts — loaded lazily, only when actually called — makes the real API request. State lives in SQLite locally and on Fly.io, or in D1 (Cloudflare's database) plus R2 (its file store) on Workers. Set one environment variable and stored credentials are encrypted with AES-256-GCM, a strong standard cipher, using a key OpenConnector never stores.
05
What you'd actually build on it
Could I use this?
The same board serves a product, a platform team, and your own desktop.
1 An agent product with durable app access product teams
Your users connect their own GitHub, Notion or Slack once; your agents act through stable, versioned action contracts. Self-host on Docker or Fly.io, deploy to Cloudflare Workers, or start on OOMOL's hosted runtime — the provider ids, action ids and schemas are identical, so you can move to self-hosted later without rewrites.
2 An instant toolbox for any MCP agent host agent builders
Point any MCP-capable host at the gateway and it discovers four tools — list_apps, search_actions, get_action_guide, execute_action — and through them, the entire catalog. You wire one endpoint instead of hundreds of bespoke tools.
http://localhost:3000/mcp3 One inspectable place for credentials platform teams
Allow/block policy per action, revocable runtime tokens, encryption at rest, and run logs with secrets redacted — plus a console that shows exactly what ran, when, and as which account. The screenshot above is the console's real catalog view, shipped in the repo.
06
From zero to a running action in three commands
How do I start?
You need Docker installed (or Node.js 22+). The published image ships the full catalog and console.
docker compose up- Start the gateway.
docker compose uppullsghcr.io/oomol-lab/open-connector:latest. You'll see the runtime boot, then the console is athttp://localhost:3000and a generated API reference athttp://localhost:3000/docs. - Prove it works — no credentials needed.
curl -s -X POST http://localhost:3000/v1/actions/hackernews.get_top_stories -H 'content-type: application/json' -d '{"input":{}}'returns a JSON envelope of live story IDs. That's a real action, end to end. - Connect a real account.
curl -s -X PUT http://localhost:3000/api/connections/github -H 'content-type: application/json' -d '{"authType":"api_key","values":{"apiKey":"github_pat_..."}}'— then callgithub.get_current_userand get your identity back, fetched with a key no agent ever saw. - Plug in your agent. Point any MCP-capable host at
http://localhost:3000/mcp, or use the Connector SDK /ooCLI from code. Next:docs/credentials.mdfor OAuth apps and encryption,docs/cloudflare.mdto deploy on Workers.
07
Take the knowledge base with you
Does my AI get it too?
Everything this page knows, packaged for your AI: a real vector knowledge base built from the OpenConnector source (566 passages), symbol and entrypoint indexes, and an MCP server your agent can query — ask it how credential encryption works and it answers from the code.