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.

Register an OAuth app once, connect with one click

An OAuth Connection needs a client registered with the provider — a Google Cloud OAuth client, a GitHub OAuth App, and so on. By default each Connection brings its own, which means whoever connects a mailbox first has to create a Google Cloud project, enable the Gmail API, configure a consent screen, register a Web client, and paste an ID and secret into the connect form. Then do it again for the next mailbox, and again in the next company. That setup, not the consent screen, is what made connecting email hard.

An instance admin can do it once for the whole install instead. Open Admin → Integrations, pick a provider, copy the redirect URI it shows into the provider's console, and paste back the Client ID and Client Secret. From then on, every company on the instance connects that provider by clicking it and approving on the provider's own screen — there is no ID to create and nothing to paste. Connecting a Gmail mailbox becomes: click Google Workspace, tick the products it may touch, approve.

One registration covers every integration that shares the app: registering Google unlocks Google Workspace, Google Analytics, Search Console, and Google Ads together. You can register Google, GitHub, Microsoft, LinkedIn, Reddit, and X.

Nothing about this is mandatory, and it does not take anything away. A company that needs its own client — a Workspace tenant with its own consent policy, a separate quota, an account the instance admin should not see — clicks Use my own OAuth client instead on the connect form, which brings back the Client ID and Secret fields; those credentials then win for that Connection. An install can mix the two freely.

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, and data Connections.
• 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.

Sites with no usable API

Every Integration talks to an API. Some sites have no usable API, or paywall the parts that matter, and a Connection cannot help you there — Genosyn no longer stores a site password on a Connection, so there is no Browser login tab on X or anywhere else. Keep the credential in the Vault instead and let an AI employee sign in with the built-in Browser.

• Store the login once. Add a Vault item carrying the site's origin, the username, the password, and its authenticator setup key if it has one.
• Grant the item, not the password. An employee with Use fills those fields through browser_fill_vault, so the plaintext never reaches the model, the Run transcript, or a log.
• Challenges stay human. Genosyn never solves a captcha or a 2FA prompt it has no setup key for. Open the live browser panel, click Take over, sign in by hand once, and the employee carries on with the session you established.

X is the connector this changes most, though not in what it can do: it stays a full OAuth Integration exposing search, timelines, posting, replies, likes, retweets, follows and DMs. What went away is its browser login auth mode, which kept a site password on the Connection row. Connect X over OAuth instead; if you need a site Genosyn ships no Integration for, keep that login in the Vault and let the built-in Browser sign in under a Grant.

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.

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.

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 exists only inside a short-lived server-owned clone or refresh operation. It is never copied into the checkout, an environment variable visible to the AI employee, or a reusable credential helper. A matching HTTPS Repository can reuse the same server-held 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.

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 built-in Browser path for the LinkedIn / X / TikTok ads UIs live on the Paid Marketing page.