Integrations

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.

Connect from the product you are using

Every product has an Integrations link in its sidebar. That page is a focused view of the company catalog: it shows the Connections and connector types that belong in the current workflow, without making you leave the product to configure them.

• Explore → Integrations shows Postgres, MySQL, and ClickHouse.
• Email → Integrations shows Google Workspace, where the Gmail product is authorized.
• Code → Integrations shows GitHub; Finance → Integrations shows payment and banking Connections.
• Revenue → Integrations includes Stripe, Gmail, data Connections, and People Data Labs for company firmographics.
• AI Employees, Skills, Routines, and Pipelines show the full catalog because they can use any granted Connection.

Open Settings → Integrations whenever you want the complete company-wide catalog. Connecting, reconnecting, checking, renaming, granting, and disconnecting work the same way in either view.

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:

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:

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:

{
  "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:

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:

{
  "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.

What ships today

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

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.

Hacker News monitoring and review

Open Settings → Integrations, choose Hacker News, and optionally enter a public HN username. Hacker News does not require an API key: the username only becomes the default profile for activity tools. Grant the Connection to an AI employee, then use a Skill or Routine to monitor the top, new, best, Ask HN, Show HN, or jobs feeds; read individual items; review bounded comment trees; watch public profile activity; or poll the official updates feed.

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 Finance → 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.

People Data Labs firmographics

Open Settings → Integrations, choose People Data Labs, and paste your own API key into a new Connection. Genosyn stores the key encrypted and keeps the provider request fixed to the company-enrichment endpoint. Give an AI Employee a Grant to this Connection only when it should be allowed to request firmographic evidence.

Use the Connection from Revenue → Data quality → Firmographic lookup. Preview shows eligible Accounts, cache hits, and the maximum number of external requests without calling the provider. The proposal step can return domain, website, industry, employee count, headquarters, and parent-company evidence, but every value waits in the Revenue evidence queue for review. Successful matches may consume your provider credits; fresh matches and no-matches are cached for 30 days by default.

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 repository-local inline credential helper. Because the helper does not contain an absolute workspace path, it works the same way in the self-hosted runtime and the isolated SaaS sandbox. A matching HTTPS Code Repository can reuse the same turn-scoped credential when the Connection is granted to that employee. Genosyn prefers an exact owner/repository allowlist match and can use the employee's sole GitHub Connection when no disambiguation is needed, so ordinary git pushes do not need a second copy of the PAT.

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.

LinkedIn

Create an app in the LinkedIn Developer Portal, add the callback URL shown by Genosyn under Auth, then enable Sign In with LinkedIn using OpenID Connect and Share on LinkedIn under Products. The default Post on member's behalf choice requests only those self-service permissions.

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.