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 reaches every one of them the same way and never has to know anything about Connections. Integration tools live in the searchable catalogue rather than the up-front working set — see How tools reach the model.

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

Brexfinance

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

Google Adspaid marketing

Meta Adspaid marketing

Microsoft Advertisingpaid marketing

Reddit Adspaid marketing

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.

Brex Cash and corporate cards

To connect your company's Brex account, sign in to Brex as an administrator, open Developer → Settings, and create a user token with the accounts.cash.readonly, transactions.cash.readonly, and transactions.card.readonly scopes. In Genosyn, open Settings → Integrations, choose Brex, and paste that token into a new Connection. Genosyn encrypts the token and never returns it to the browser after creation.

The Connection contributes read-only cash-account, Cash transaction, and card transaction tools to employees who receive a Grant. To bring Cash transactions into the books, open Finance → Reconciliation, create a Brex Cash feed, choose the Connection and Cash account, then click Sync.

For corporate card accounting, open Finance → Card expensesand map the Brex Connection to a card liability, default expense category, and payment account. Brex exposes only settled transactions: pending card activity appears after it settles.

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.

Searching busy Gmail inboxes

Gmail search results are paginated. If a call to gmail_search_messages returns a nextPageToken, the employee passes that value back as pageToken with the same query and labels. It repeats this until Gmail omits nextPageToken, so busy date windows are scanned in full instead of stopping at the first 100 messages.

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.

Ad platforms (paid marketing)

Four ad-platform integrations — Google Ads, Meta Ads, Microsoft Advertising, Reddit Ads — give AI employees read-first campaign visibility plus a tiny, approval-gated mutation surface (pause / enable / budget change) bounded by per-Connection spending caps and a kill switch. Spend increases queue in the Approvals inbox by default; pausing never does. Setup recipes, the full safety model, and the browser-based fallback for LinkedIn / X / TikTok live on the Paid Marketing page.