Connections to other services

connections lets an app agent act in another service for a person, within the scopes they agreed to. Reach for it to read their Gmail, post to Slack or open GitHub.

An agent may use only the scopes main.yaml gives it, risky scopes wait for a person's yes, and every use is logged. The app never sees a password.

Spec connections, for 0.3. Status: experimental, so it is imported from mainsdk/experimental/connections and may change before it is stable.

connections:
  store: db
  callback: /api/connections/callback
  providers:
    github:
      preset: github
      client-id: Iv1.4f…
      client-secret: secret:GITHUB_OAUTH_SECRET
      scopes: [read:user, repo]
      step-up: [repo]
agents:
  support-bot:
    connections:
      github: [read:user]

import { connections } from "mainsdk/experimental/connections";

const res = await connections.fetch("github", "https://api.github.com/user", {
  scope: "read:user", agent: "support-bot", user,
});

import { createFakeOAuth, createTestApp } from "@mainsdk/testing";

const fake = createFakeOAuth({
  authorize: "https://github.com/login/oauth/authorize",
  token: "https://github.com/login/oauth/access_token",
  apiHosts: ["api.github.com"],
});
const app = createTestApp({ yaml: "schema: 1\nconnections:\n  store: memory\n  providers:\n    github:\n      preset: github\n      client-id: cid\n      scopes: [read:user]\n" });
// connect, play the person's consent with fake.consent(redirect), then call the callback

connections:
  driver: google

Quick start

connections:
  providers:
    github:
      preset: github
      client-id: Iv1.4f…
      client-secret: secret:GITHUB_OAUTH_SECRET
      scopes: [read:user, repo]
      step-up: [repo]
agents:
  support-bot:
    connections:
      github: [read:user]

import { connections } from "mainsdk/experimental/connections";

export async function GET(req: Request) {
  return connections.connect(req, "github", { returnTo: "/settings/accounts" });
}

connect returns a redirect to the provider's consent screen, with PKCE (S256), a single-use state that is bound to the person's session and lives ten minutes, and the exact redirect_uri. Mount connections.callback(req) at the callback path; it checks the state, the session and the issuer (RFC 9207), swaps the code, seals the tokens and returns { connection, returnTo }.

Configuration

connections:
  store: db                     # db (the tenant's region) | memory (tests and local mode)
  callback: /api/connections/callback
  providers:
    gmail:
      preset: google            # google, github, slack, microsoft, notion, atlassian, airtable
      client-id: 1234.apps.googleusercontent.com
      client-secret: secret:GOOGLE_OAUTH_SECRET
      scopes: [https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/gmail.send]
      hosts: [gmail.googleapis.com]
      step-up: [https://www.googleapis.com/auth/gmail.send]
    partner:                    # no preset: declare every endpoint
      authorize: https://id.partner.com/oauth/authorize
      token: https://id.partner.com/oauth/token
      revoke: https://id.partner.com/oauth/revoke
      issuer: https://id.partner.com
      client-id: abc
      scopes: [items:read]
      hosts: [api.partner.com]
agents:
  support-bot:
    connections:                # the only scopes this agent may use, per provider
      gmail: [https://www.googleapis.com/auth/gmail.readonly]

Client secrets go in as secret: references. A provider with no preset must declare its authorize, token and hosts.

What you get

The providers with a preset are google, github, slack, microsoft, notion, atlassian and airtable; any other OAuth provider declares its endpoints. store: memory keeps connections in this process for tests and local mode.

Examples

Call the provider as an agent

import { connections } from "mainsdk/experimental/connections";

declare const user: { id: string };   // the signed-in person

const res = await connections.fetch("gmail", "https://gmail.googleapis.com/gmail/v1/users/me/messages", {
  scope: "https://www.googleapis.com/auth/gmail.readonly",
  agent: "support-bot",
  user,
});

scope is required and must be one the agent holds. If the scope is in step-up, the call returns Pending while the person decides.

Show the person what they are agreeing to

import { connections } from "mainsdk/experimental/connections";

const info = connections.describe("gmail");
// info.scopes: [{ scope, text, stepUp }], info.agents: [{ agent, scopes }]

Use describe to render your own consent screen. It returns a line of text for each scope.

List and revoke

import { connections } from "mainsdk/experimental/connections";

const { items } = await connections.list({ limit: 20 });
await connections.revoke(items[0].id, { reason: "user removed the account" });

Revoking tells the provider (RFC 7009) and deletes the tokens at once. If the provider cannot be reached, a connections.revoke job holds a separately sealed copy of the token and retries until the provider accepts it; nothing else can read it. No agent can use the grant after revoke.

Reach a remote MCP server with OAuth

mcp:
  servers:
    - { name: docs, url: https://mcp.example.com/mcp, auth: oauth }
connections:
  mcp:
    dynamic-registration: true   # register with the server's authorization server (RFC 7591)

The first call gets a 401 with resource_metadata. The client reads the protected resource metadata (RFC 9728) and the authorization server's metadata (RFC 8414), registers once, and answers with MAIN-CONN-0002 until the person connects with connections.connect(req, "mcp:docs", { returnTo }). That redirect carries resource=<server URL> (RFC 8707) and PKCE. Metadata about another resource fails with MAIN-MCP-0007; an authorization server with no registration endpoint and no client-id fails with MAIN-MCP-0008; an authorization server host that network does not allow fails with MAIN-NET-0002.

Let your own MCP server take OAuth tokens

mcpServer({ actions, oauth: { resource, issuer } }) serves its protected resource metadata at /.well-known/oauth-protected-resource, refuses a token issued for another resource (MAIN-MCP-0009, 401) and a token without the tool's scope (MAIN-MCP-0010, 403 with error="insufficient_scope"), and refuses a token in the query string. The app is never an authorization server: issuer is your auth driver's issuer.

Errors and checks

The other runtime codes (MAIN-CONN-0001, 0006, 0008, 0009, 0010, and MAIN-MCP-0007 to 0010) are listed in check codes.

Swapping drivers

A connection is a grant to one provider, so there is no driver to swap. To move to another provider, add it under providers, have the person connect, and point the agent's connections at the new scopes.

Testing

createTestApp with connections: { store: memory } keeps connections in the process. createFakeOAuth from @mainsdk/testing stands in for the provider: it checks PKCE and the exact redirect_uri, rotates refresh tokens, and can answer invalid_grant or go down. Nothing leaves the process. See the testing kit.

import { createFakeOAuth, createTestApp } from "@mainsdk/testing";

const fake = createFakeOAuth({
  authorize: "https://github.com/login/oauth/authorize",
  token: "https://github.com/login/oauth/access_token",
  apiHosts: ["api.github.com"],
});
const app = createTestApp({ yaml: "schema: 1\nconnections:\n  store: memory\n  providers:\n    github:\n      preset: github\n      client-id: cid\n      scopes: [read:user]\n" });
// connect, play the person's consent with fake.consent(redirect), then call the callback

Security and privacy

• Tokens are sealed with the person's key (the tenant's for a tenant connection) and never returned to the app, a listing, a log or an error. Destroying the person's key makes the connection unusable (MAIN-CONN-0007).
• A token goes only to the provider's hosts, over https.
• Every use is written to the audit log with the agent, the scope and the person.

FAQ

Does the person need to connect for each agent? No. Connect once; each agent is limited by its own connections list.

Can a tenant own a connection instead of a person? Yes, with for: "tenant", which needs the connections.manage permission.

Next

• Auth and sessions: who the person is.
• Keys: where the grant is sealed.
• Imports: pull from a provider on a schedule.
• Actions and MCP: the same grants reach remote MCP servers.