Connections (MCP)

createMcpConnections, a connection's options, and signing in with OAuth, from @intentface/latch-mcp.

@intentface/latch-mcp gives agents the tools of MCP servers, signed in as each user. What it's for: Tools and connections. Setting it up: Connect other services.

import { createVault } from "@intentface/latch-core";
import { createPostgresSecretStore } from "@intentface/latch-drizzle";
import { createMcpConnections, oauth, bearer } from "@intentface/latch-mcp";

const vault = createVault<Principal>({
  store: createPostgresSecretStore(db, { owner: (p) => [p.orgId, p.userId] }),
  masterKey: process.env.LATCH_MASTER_KEY!, // base64 of 32 random bytes
});

createRuntime({
  …,
  connections: createMcpConnections({
    vault,
    secrets: vault.resolver,
    allowedHosts: ["mcp.linear.app", "mcp.internal.example.com"],
    callbackBaseUrl: "https://app.example.com/api/latch/connections",
    connections: {
      linear: { url: "https://mcp.linear.app/mcp", auth: oauth() },
      crm: { url: "https://mcp.internal.example.com/crm", auth: bearer({ getToken: (p) => vault.resolver(p, "crm_token") }) },
    },
  }),
});

createMcpConnections

Option	Type	Default
`vault`	`Vault<P>`	—
Where each user's tokens are kept, encrypted. From `createVault`. `Vault<P>`
`secrets?`	`SecretResolver<P>`	—
Reads secrets for `bearer` connections, usually `vault.resolver`. `SecretResolver<P> \| undefined`
`allowedHosts`	`string[] \| ((principal: P) => string[] \| Promise<string[]>)`	—
The hosts connections may reach, for example `["mcp.linear.app"]`. A request anywhere else is refused, so a connection URL can't be pointed at an unexpected server. Pass a function to allow different hosts per caller. `string[] \| ((principal: P) => string[] \| Promise<string[]>)`
`connections`	`Record<string, McpConnectionDef<P>>`	—
The services, by the name agents use in `connections: ["…"]`. `Record<string, McpConnectionDef<P>>`
`callbackBaseUrl?`	`string`	—
Where sign-ins return to, for example `https://app.example.com/api/latch/connections`. Each service's redirect URL is this plus `/<name>/callback`; register that URL with providers that ask for one. `string \| undefined`
`onConnectionError?`	`((name: string, error: unknown) => void)`	—
Called when a service can't be reached for a turn. The turn goes on without its tools. `((name: string, error: unknown) => void) \| undefined`

A connection

Option	Type	Default
`url`	`string`	—
The MCP server's URL (streamable HTTP). `string`
`description?`	`string`	—
What the service is for. Shown to the user, and helps the model pick it. `string \| undefined`
`auth?`	`McpConnectionAuth<P>`	—
How to sign in: `oauth()`, `bearer({ getToken })` or `headers({…})`. Leave out for a server without sign-in. `McpConnectionAuth<P> \| undefined`
`tools?`	`object`	—
Only offer some of the server's tools (`allow`), or hide some (`block`), by the server's own tool names. `{ allow?: string[]; block?: string[]; } \| undefined`
`approval?`	`McpApprovalPolicy`	—
Which tools need a person's approval. `"destructive"` (the default) asks for tools the server marks as destructive or as not read-only; tools the server doesn't mark at all run without asking. `"all"`, `"none"`, or a per-tool predicate `(tool) => boolean` — which may instead return a per-CALL function `(input) => boolean \| Promise<boolean>`, evaluated with the model's arguments each call, for meta-tool servers whose one tool multiplexes every operation (gate `execute_tool` only when `input.toolName` starts with `create_`). For policy that varies by caller, use approvalFor instead. `McpApprovalPolicy \| undefined`
`approvalFor?`	`(principal: P) => McpApprovalPolicy \| Promise<McpApprovalPolicy>`	—
Like `approval`, but decided per caller, for example from their permissions. Used instead of `approval` when set. `((principal: P) => McpApprovalPolicy \| Promise<McpApprovalPolicy>) \| undefined`
`visibleTools?`	`((tool: McpToolInfo) => boolean)`	—
Hides tools: one it returns `false` for isn't offered at all. For a rule that depends on the caller, use `visibleToolsFor`. `((tool: McpToolInfo) => boolean) \| undefined`
`visibleToolsFor?`	`function`	—
Like `visibleTools`, but decided per caller. Used instead of `visibleTools` when set. `((principal: P) => ((tool: McpToolInfo) => boolean) \| Promise<(tool: McpToolInfo) => boolean>) \| undefined`
`allowPrivateHost?`	`boolean`	—
Lets this connection reach a private address (localhost, your internal network). Blocked by default, including names that resolve to one; turn it on only for a server you run yourself. `boolean \| undefined`

Signing in: oauth()

oauth() with no options works for servers that let apps register themselves. For the rest, pass your own app's clientId and clientSecret.

Option	Type	Default
`scopes?`	`string[]`	—
The permissions to ask for, for example `["read", "write"]`. `string[] \| undefined`
`clientId?`	`string`	—
Your app's client id at the provider. Leave it out and Latch registers an app with the server automatically, which most MCP servers allow. Google, GitHub, Slack and most large providers don't: create an app there, add `<callbackBaseUrl>/<name>/callback` as a redirect URL, and pass its id. `string \| undefined`
`clientSecret?`	`string`	—
Your app's client secret, with `clientId`. Leave out for a public client. `string \| undefined`
`clientName?`	`string`	—
The app name shown to users when Latch registers automatically. `string \| undefined`
`tokenEndpointAuthMethod?`	`string`	`"none" (a public client)`
How the app proves itself when exchanging codes for tokens. `string \| undefined`
`normalize?`	`object`	—
Normalize a provider's non-conformant discovery documents (e.g. a proxied `http://` authorization-server reference, or a trailing-slash issuer the SDK's strict RFC 8414 check rejects). `forceScheme: "https"` is the common case; `hosts` bounds the rewrite to those hostnames. `{ forceScheme?: "https" \| "http"; hosts?: string[]; } \| undefined`
`omitResource?`	`boolean`	—
Omit the RFC 8707 `resource` parameter from the authorization request and token exchange even when the server's protected-resource metadata advertises one. Google's MCP servers (calendarmcp.googleapis.com, …) do advertise a resource, but the audience-bound token Google then mints is rejected by the MCP server itself (401 `invalid_token`); a plain scope-bearing token is accepted. Set `true` for those servers. `boolean \| undefined`
`authorizationParams?`	`Record<string, string>`	—
Extra query params appended to the authorization redirect URL — provider extensions the SDK doesn't model, e.g. Google's `{ access_type: "offline", prompt: "consent" }` to be issued a refresh token (without it the connection silently dies when the 1h access token expires, since Google returns no refresh token by default). `Record<string, string> \| undefined`
`clientMetadata?`	`Partial<object>`	—
Extra client-metadata passthrough (merged into the generated metadata). Partial<{ redirect_uris: string[]; application_type?: "native" \| "web" \| undefined; token_endpoint_auth_method?: string \| undefined; grant_types?: string[] \| undefined; response_types?: string[] \| undefined; client_name?: string \| undefined; client_uri?: string \| undefined; logo_uri?: string \| undefined; scope?: string \| undefined; contacts?: string[] \| undefined; tos_uri?: string \| undefined; policy_uri?: string \| undefined; jwks_uri?: string \| undefined; jwks?: any; software_id?: string \| undefined; software_version?: string \| undefined; software_statement?: string \| undefined; }> \| undefined
`allowedAuthorizationServers?`	`string[]`	—
Origins permitted to act as this connection's authorization server. Defaults to the MCP server's own origin — set this only when the server genuinely delegates authorization to a separate IdP, and list that IdP's origin. See `McpOAuthConfig.allowedAuthorizationServers`. `string[] \| undefined`

bearer({ getToken }) sends a token you supply, and headers({ … }) sends fixed headers.