Brains & tools

Integrations

An Integration is a connector type — Stripe, Gmail, GitHub, Postgres. A Connection is one authenticated account inside an integration. A Grant gives an AI employee access to one Connection.

Three words, three rows

Integration: A connector type, defined in code under server/integrations/providers/. Static catalog — you add one by writing a provider file, not by clicking a button.
Connection: One authenticated account inside an integration. DB row (IntegrationConnection), per-company. You might have two Stripe connections — "live" and "test".
Grant: A row on EmployeeConnectionGrant giving one employee access to one connection. Without a grant, the employee's MCP server simply doesn't list those tools.

How tools show up

Every run, the in-process agent regenerates the MCP server list. The built-in genosyn server lists every integration tool the employee has a Grant for; the agent sees a flat catalog of tools and never has to know anything about Connections.

Connecting an external MCP client

The built-in genosyn tools an employee gets inside a run — the same tool catalog the in-process agent loads per run — are also reachable over the network. Point any MCP client at an employee's endpoint and it drives that employee from anywhere: Claude Desktop, Cursor, VS Code, or your own agent, all seeing the same tools, Grants, and audit trail as the in-app assistant.

Get the endpoint URL

Open the employee's MCP servers tab. The Connect an external harness panel at the top shows a copyable URL:

text

https://<your-genosyn-host>/api/companies/<company-id>/employees/<employee-id>/mcp/connect

The ids are the company and employee UUIDs, wired in for you — just copy it. Whichever employee the URL names is the one the client acts as: every call runs with that employee's Grants and lands in its journal.

Authenticate

Requests carry a Genosyn API key as a bearer token — the same durable credential the REST API uses. Mint one at Settings → API keys with Generate key; the plaintext is shown exactly once, so copy it then. Send it on every request:

http

Authorization: Bearer gen_xxxxxxxx…

A key is scoped to a single company and authenticates as the member who minted it. Browse the full REST surface at API reference.

Transport & client config

The endpoint speaks the MCP Streamable HTTP transport and is stateless — the client POSTs JSON-RPC and reads a JSON reply, with no session to keep alive. Any client that takes a remote server as { url, headers } connects natively:

json

{
  "mcpServers": {
    "genosyn": {
      "url": "https://<your-host>/api/companies/<company-id>/employees/<employee-id>/mcp/connect",
      "headers": { "Authorization": "Bearer gen_xxxxxxxx…" }
    }
  }
}

Claude Code registers it in one command:

bash

claude mcp add --transport http genosyn \
  "https://<your-host>/api/companies/<company-id>/employees/<employee-id>/mcp/connect" \
  --header "Authorization: Bearer gen_xxxxxxxx…"

Claude Desktop has no field for a custom auth header yet, so bridge the endpoint through mcp-remote in claude_desktop_config.json. Keep the token in an env var, where its space survives — passed as a raw --header arg it can get mangled:

json

{
  "mcpServers": {
    "genosyn": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<your-host>/api/companies/<company-id>/employees/<employee-id>/mcp/connect",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer gen_xxxxxxxx…" }
    }
  }
}

Cursor and VS Code use the same url + headers shape (VS Code names the block servers and prompts for the token as an input); any stdio-only client can reach the endpoint through the same mcp-remote bridge.

An API key is a company-wide credential.

Any valid key for a company can drive any employee in it — there is no per-employee scope beyond company membership — and every write runs as that employee, landing in its audit log and journal. Serve Genosyn over HTTPS, keep keys out of committed config, and revoke a leaked one at Settings → API keys.

What ships today

A non-exhaustive sampling of integrations available in the latest image:

GitHubengineering

Stripefinance

Gmail / Googlecomms + drive

Google Analyticsanalytics

Google Search ConsoleSEO / search

Notionknowledge

Airtabledata

Lineartickets

Telegramcomms

Postgres / MySQL / ClickHousedatabases

Rediscache / KV

Metabase / NocoDBBI / data

Lightning (NWC + LND)payments

Nostrsocial

Reddit, X, LinkedInsocial

Adding an Integration

Integrations live in code: a file under server/integrations/providers/ exports the auth flow, config shape, and MCP tools the integration contributes. Once compiled, the integration appears in the UI for any company on that instance — no per-tenant flag.

Grants & revocation

Add a grant on the employee's Connections page. The MCP tool list updates on the next run.
Revoke a grant the same place. The next routine won't see the tools.
Delete a Connection at the company level. All dependent grants disappear with it.

GitHub & engineering grants

GitHub is special: a Connection holds a list of repos the employee is allowed to touch, and the runner materializes a git checkout of each allowed repo into data/companies/<co>/employees/<emp>/repos/... before each run. The git token never lands on disk — it's read from the env var the runner injects, via a per-connection credential helper inside .git/genosyn-cred.sh.

Lightning payments

The Lightning integration adds spending caps on the Connection itself: maxPaymentSats, dailyLimitSats, requireApprovalAboveSats. Over-cap payments queue a lightning_payment Approval that replays the call once a human ✓'s it.

Emailing files from Resources

An employee drafting or sending mail through the Google Workspace connector can attach Resources it has been granted — the ebook you uploaded, a contract, a report. It names the resource by slug and Genosyn reads the bytes server-side, so the file never has to travel through the model. Attachments work the same on a draft as on a send: the draft lands in Gmail with the files already on it, ready for a human to review before it goes out.

Each attachment picks a format. The default, original, sends the file exactly as it was uploaded — that is what you want for a PDF or EPUB that already exists. The other four (pdf, html, md, txt) render the resource's extracted text into a new document, the same rendering the Download menu on the resource page produces. Those are the only options for link- and paste-kind resources, which never keep an original file.

Who may send at all is a separate question, and the Email section owns it. Once you connect a mailbox there, the gmail_* tools honour that mailbox's Read / Draft / Send level — so an employee on the default Draft can attach a Resource to a draft for you to review, but cannot send it itself. Until a mailbox is connected there is no level to honour, and a Connection grant alone lets an employee send.

Google Analytics & Search Console

Two read-only Google integrations for the team's growth work, listed under Analytics in the catalog and separate from the Gmail / Drive Google Workspace connector. Google Analytics exposes GA4 accounts and properties plus report tools (sessions, users, conversions, channels, realtime, and the dimension/metric catalog). Google Search Console exposes verified sites, Search Analytics (clicks, impressions, CTR, position), sitemaps, and URL inspection.

Connect either with your own OAuth client (add the callback URI the modal shows to your Google Cloud OAuth client) or a service-account JSON key — for a service account, add its email as a viewer/user on the GA4 property or Search Console site; no domain-wide delegation is needed. Both request only the read-only scope (analytics.readonly / webmasters.readonly), so employees can report on traffic and search performance but never change settings.