@nuxtagentic/integrations

Integrations

Integrations is a core feature, always available from the dashboard sidebar at /dashboard/integrations. Search the catalog, connect an account and select the actions agents may use. No accounts are connected automatically.

Connections run on CloudConfig Connect. An integration connects in one of three ways, offered in this order:

• OAuth with your registered provider app: pnpm exec cloudconfig connect add github guides registration, prints callback and webhook URLs, and saves the credentials you supply.
• Hosted MCP servers (Linear, Notion, Sentry, Stripe, or any URL): compatible servers support sign-in without manual app registration. Their tools become the actions; tools not marked read-only ask for approval by default.
• A pasted API token, for providers without OAuth here and as the fallback while an OAuth app is not registered yet.

Google integrations (Gmail, Calendar, Drive, Analytics, Search Console, Ads) use their own Google grant, separate from Google sign-in, so the mailbox an agent reads need not be the account someone signs in with. Google Ads also reads the app's NUXT_GOOGLE_ADS_DEVELOPER_TOKEN; the customer ID is a per-connection setting.

Send email with Gmail or Cloudflare

Connect Gmail when an agent needs to read an inbox, draft replies or send as the person who connected their mailbox. From your application directory, run pnpm exec cloudconfig connect add google, enable the Gmail API in that Google Cloud project and register the callback URL printed by the CLI. Then connect Gmail in Integrations and allow the actions your agent needs. Gmail uses OAuth and its own grant, separate from application sign-in.

Connect Cloudflare Email Sending when an agent should send reports or notifications from your domain:

1. Onboard your sender domain in Cloudflare Email Sending and finish its DNS authentication. Sending to arbitrary recipients requires Workers Paid; Email Sending is currently in beta.
2. Create a Cloudflare API token with Email Sending Write for the sending account. Copy that account's 32-character ID.
3. Open Integrations → Cloudflare Email Sending and enter the API token, account ID and sender email, such as notifications@example.com. Choose Whole workspace to share the connection; only organization owners and admins can add shared connections. Just me limits it to your own runs.
4. Add Send email to your agent's Tools drawer. Every send waits for approval in Integrations before contacting Cloudflare.

The connection check reads the account's Email Sending suppressions endpoint; it does not send a test message or verify the sender's DNS setup. Cloudflare checks the sender domain and sending authorization when the approved action executes. Connect seals the credentials in your database. No Cloudflare OAuth app, Worker email binding or additional application environment variables are needed.

The sender and account are fixed by the connection. The action accepts one to address, a subject, text and/or html, and an optional reply_to address:

import { createIntegrationCommands } from '@nuxtagentic/integrations/client'

const integrations = createIntegrationCommands(useRequestFetch())
await integrations.action('cloudflare-email', 'send_email', {
  body: {
    to: 'owner@example.com',
    subject: 'Weekly agent report',
    text: 'The agent completed its weekly review.',
  },
})

This returns a pending approval, not a sent email. After approval, the result preserves Cloudflare's delivered and queued recipient lists; queued mail is still awaiting delivery. Bounced or suppressed recipients fail the action. Cloudflare sends are not automatically retried by this adapter because its REST API does not document an idempotency key. See the Cloudflare REST API.

Cloudflare Email Sending is an agent tool, also usable by agents in automations. The automation Send email / Notify owner outcomes still use Gmail. Connecting Cloudflare here does not configure application authentication or email OTP delivery.

Google-hosted MCP tools

Set NUXT_GOOGLE_MCP_ENABLED=true to use Google's hosted MCP servers for compatible Calendar, Gmail draft, and Drive actions. The default is false while these servers require Google Workspace Developer Preview access. This reuses the Google account already connected through CloudConfig Connect and the same CONNECT_GOOGLE_CLIENT_ID and CONNECT_GOOGLE_CLIENT_SECRET. It does not use the application's Google sign-in session or require a second account grant.

Before enabling the setting:

1. Join the Google Workspace Developer Preview Program.
2. Enable Calendar, Gmail, and Drive APIs and their MCP services in the OAuth app's Google Cloud project (calendarmcp.googleapis.com, gmailmcp.googleapis.com, and drivemcp.googleapis.com). Register the existing /api/connect/google/callback URL and configure the OAuth client for an AI-powered agent.
3. Keep the scopes declared in cloud.config.ts: calendar.events authorizes event creation, gmail.modify covers drafts and REST email actions, and drive.file limits file access to the grant. MCP does not bypass consent or Google verification.
4. Configure Google's required content screening, for example Model Armor floor settings that screen MCP calls and responses in the project. A custom screening solution must be documented as Google requires.
5. Set the environment variable and restart or deploy the application. The host's deploy.optionalSecrets includes this setting.

The source config explicitly allows only Google's three MCP endpoint URLs to receive Google account tokens. CloudConfig 0.2.0-beta.6 includes endpoint allowlists, token refresh, permission handling, and request cancellation directly; this release needs no custom CloudConfig patch.

Existing agent tool names, action parameters, connection permissions, and automation definitions remain valid. Compatible requests use list_events, create_event, create_draft, search_files, or create_file. Calendar event lists and Drive file metadata are normalized to the existing field names. With MCP enabled, Calendar event creation, Gmail drafts, and Drive file creation require owner approval before execution.

REST remains available for Gmail reads and sends, thread-linked drafts, Drive moves, Analytics, Ads, Search Console, API-key connections, and requests whose options the MCP tools cannot represent faithfully. Calendar attendees/all-day events, advanced queries, and binary file metadata creation also retain their REST behavior. An MCP authorization, service, or tool error is reported directly; an action is never retried through REST after an MCP failure. Scheduled monitors and event triggers remain application code. An MCP permission or service rejection does not disable the shared Google grant used by REST actions. Authentication failures retry once with a refreshed token.

See Google's Calendar, Gmail, and Drive setup guides.

Who a connection belongs to

• Just me — agents and automations act as the person who connected it, and only their own runs may use it.
• Whole workspace — added by an organization owner or admin and shared with every member's runs. Prefer it for bots and installations (GitHub App, Slack): it keeps working after the person who added it leaves.

An integration can have several accounts. The first keeps the plain tool names (github_open_and_label_issues); further accounts add their id (github_7_open_and_label_issues). Automations act as their owner, or — with Acts as → Workspace only — use only shared connections. Runs re-check membership: when the owner leaves, their automations pause and their personal connections are revoked at the vendor.

Credential storage

Tokens and keys are sealed by Connect in this database under CLOUDCONFIG_CONNECT_KEY and bound to their row; nothing here stores a token. Development creates .cloudconfig/connect.key; production requires the key (pnpm exec cloudconfig connect key). Rotate with --rotate; the Worker's cron refreshes tokens ahead of expiry and re-seals after a rotation.

Connecting verifies the account with the provider before enabling it. Disconnecting removes the integration and revokes the account at the vendor once nothing else uses it. Every action reloads permissions and membership from the server; saving a tool in an agent never grants additional permissions. Stripe refunds, Intercom reply drafts and MCP tools marked Ask first create pending approvals. Review their parameters in the Integrations page; Approve executes the action, while Reject leaves the provider unchanged.

Agent commands

Model records use the existing CloudConfig client and MCP tools. Runtime commands are available separately; use an authenticated transport such as Nuxt's useRequestFetch() so the account and active workspace remain attached:

import { createIntegrationCommands } from '@nuxtagentic/integrations/client'

const integrations = createIntegrationCommands(useRequestFetch())
const tools = await integrations.tools()
await integrations.action('github', 'open_and_label_issues', {
  owner: 'your-company',
  repo: 'internal-agent',
  body: { title: 'Investigate this incident', body: 'Agent findings…', labels: ['triage'] },
})

tools() returns the actual connected and permitted action names, JSON parameter schemas, and the account each one acts through. Pass a connection id as the fourth argument of action() to choose one of several accounts. The suggestions at the bottom of Agents → Tools add those handlers to a saved agent. Automations executes only enabled tools with a connected handler. Arbitrary custom declarations remain portable metadata; add a runtime handler before executing them, or disable them.

Adapter inputs contain path parameters, optional query and write body fields. API hosts, HTTP methods and GraphQL operations are owned by the server adapter; agents cannot choose them. Provider-specific pagination and filters belong in query. Write bodies use the provider's documented fields. Narrow actions restrict their fields: pausing ads cannot edit creatives, updating a deal stage cannot edit other contact properties, and moving Drive files cannot modify file metadata. For Gmail, supply messageId to read a full message, or omit it to list messages. Google Ads bid/budget updates use resource: 'bid' | 'budget' with update operations.

Events

Vendor webhooks for GitHub (App), Slack, Shopify, HubSpot, Intercom and Notion arrive at /api/connect/hooks/<provider> — the URL cloudconfig connect add prints. Connect verifies the signature, and the event starts the automations of everyone who can see the connection: its owner for a personal one, every member for a shared one.

For other senders, open a connection and choose Event endpoint. POST a normalized event to /api/integration-hooks/<id>, authenticated with the connection's secret — as a bearer token, as a GitHub repository webhook secret, or as Connect's X-CloudConfig-Signature:

{
  "event": "github.an_issue_is_created",
  "id": "unique-provider-event-id",
  "payload": { "issue": { "number": 42, "title": "Investigate an incident" } }
}

Repeated event IDs reuse the existing run. Analytics thresholds, weekly reports and upcoming calendar events require a monitor or scheduler to emit the corresponding event; connecting an account does not create one. Agents can emit normalized events with the Automations command helper.

Add a provider

Keep its browser-safe definition in runtime/shared/catalog.ts — including auth (a Connect OAuth provider and scopes, apiKey, or an MCP server) and ownership — and its fixed endpoints, verification request and action restrictions in runtime/server/utils/integration-adapters.ts. Enable the OAuth provider under connect.providers in cloud.config.ts. Keep permissions explicit. New catalog entries do not need new database tables; an MCP server needs only a catalog entry.

Add its brand SVG to runtime/assets/logos/<logo>.svg, matching the catalog's logo key. The cards and connection dialogs share runtime/components/IntegrationLogo.vue and preserve the SVG's colors. Logos are bundled locally from SVG Logos and Simple Icons; Search Console uses Google's current logo. Monochrome marks use a light variant in dark mode; TikTok keeps its cyan and red accents with a white center.