AI-Native SaaS Path

Build the default Weavz flow for AI-native SaaS products: workspace integrations, end-user auth, MCP servers, and per-user MCP tokens.

AI-Native SaaS Path

Most Weavz customers build AI-native SaaS products. The default path is not to have your agent call the Actions API directly. The default path is to prepare a workspace, add workspace integrations with stable aliases, let users connect accounts, create an MCP server for the workspace, then give your agent harness an MCP endpoint and scoped token.

Use direct REST or SDK action execution for smoke tests, backend jobs, webhooks, and product flows that are not driven by an MCP client. For agent runtime, MCP should usually be the handoff point.

The default loop

Create one workspace for the customer, project, team, or agent environment you want to isolate.
Add workspace integrations with stable aliases such as customer_slack, files, state, and browser.
Register your app's user as an end user in that workspace.
Send the user a hosted connect URL for any integration that needs their credentials.
Create a Code Mode MCP server for the workspace.
For hosted MCP clients, use MCP OAuth. For app-owned agent harnesses, issue a per-end-user MCP bearer token.
Plug mcpEndpoint and the mcp_... token into your harness. The agent discovers and calls workspace integrations by alias.

flowchart LR
  App["Your SaaS backend"] --> Workspace["Workspace"]
  Workspace --> WI["Workspace integrations"]
  App --> EndUser["End user"]
  EndUser --> Connect["Hosted connect"]
  WI --> MCP["MCP server"]
  EndUser --> Token["Per-user MCP token"]
  MCP --> Harness["Agent harness"]
  Token --> Harness

1. Prepare the workspace integrations

Workspace integrations are the product contract your agents call. The alias is more important than the catalog integration name because the alias becomes the executable tool namespace in MCP.

This example adds:

customer_slack as a per-user Slack integration
files for workspace files
state for workspace key-value state
browser for hosted browser control

bash

curl -X POST https://api.weavz.io/api/v1/workspaces \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Agent Workspace", "slug": "acme-agent-workspace" }'
 
curl -X POST https://api.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "alias": "customer_slack",
    "connectionStrategy": "per_user",
    "enabledActions": ["send_channel_message", "list_channels"]
  }'
 
curl -X POST https://api.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "storage",
    "alias": "files",
    "settings": { "persistence": { "scope": "workspace" } }
  }'
 
curl -X POST https://api.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "kv-store",
    "alias": "state",
    "settings": { "persistence": { "scope": "workspace" } }
  }'
 
curl -X POST https://api.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "integrationName": "agent-browser", "alias": "browser" }'

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: process.env.WEAVZ_API_KEY! })
 
const { workspace } = await client.workspaces.create({
  name: 'Acme Agent Workspace',
  slug: 'acme-agent-workspace',
})
 
const { integration: customerSlack } = await client.workspaces.addIntegration(workspace.id, {
  integrationName: 'slack',
  alias: 'customer_slack',
  connectionStrategy: 'per_user',
  enabledActions: ['send_channel_message', 'list_channels'],
})
 
await client.workspaces.addIntegration(workspace.id, {
  integrationName: 'storage',
  alias: 'files',
  settings: { persistence: { scope: 'workspace' } },
})
 
await client.workspaces.addIntegration(workspace.id, {
  integrationName: 'kv-store',
  alias: 'state',
  settings: { persistence: { scope: 'workspace' } },
})
 
await client.workspaces.addIntegration(workspace.id, {
  integrationName: 'agent-browser',
  alias: 'browser',
})

python

import os
from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key=os.environ["WEAVZ_API_KEY"])
 
workspace = client.workspaces.create(
    name="Acme Agent Workspace",
    slug="acme-agent-workspace",
)["workspace"]
 
customer_slack = client.workspaces.add_integration(
    workspace["id"],
    integration_name="slack",
    integration_alias="customer_slack",
    connection_strategy="per_user",
    enabled_actions=["send_channel_message", "list_channels"],
)["integration"]
 
client.workspaces.add_integration(
    workspace["id"],
    integration_name="storage",
    integration_alias="files",
    settings={"persistence": {"scope": "workspace"}},
)
 
client.workspaces.add_integration(
    workspace["id"],
    integration_name="kv-store",
    integration_alias="state",
    settings={"persistence": {"scope": "workspace"}},
)
 
client.workspaces.add_integration(
    workspace["id"],
    integration_name="agent-browser",
    integration_alias="browser",
)

typescript

const headers = {
  'Authorization': `Bearer ${process.env.WEAVZ_API_KEY}`,
  'Content-Type': 'application/json',
}
 
const workspaceRes = await fetch('https://api.weavz.io/api/v1/workspaces', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'Acme Agent Workspace',
    slug: 'acme-agent-workspace',
  }),
})
const { workspace } = await workspaceRes.json()
 
const slackRes = await fetch(`https://api.weavz.io/api/v1/workspaces/${workspace.id}/integrations`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    integrationName: 'slack',
    alias: 'customer_slack',
    connectionStrategy: 'per_user',
    enabledActions: ['send_channel_message', 'list_channels'],
  }),
})
const { integration: customerSlack } = await slackRes.json()
 
for (const integration of [
  {
    integrationName: 'storage',
    alias: 'files',
    settings: { persistence: { scope: 'workspace' } },
  },
  {
    integrationName: 'kv-store',
    alias: 'state',
    settings: { persistence: { scope: 'workspace' } },
  },
  { integrationName: 'agent-browser', alias: 'browser' },
]) {
  await fetch(`https://api.weavz.io/api/v1/workspaces/${workspace.id}/integrations`, {
    method: 'POST',
    headers,
    body: JSON.stringify(integration),
  })
}

python

import os
import httpx
 
headers = {"Authorization": f"Bearer {os.environ['WEAVZ_API_KEY']}"}
 
workspace = httpx.post(
    "https://api.weavz.io/api/v1/workspaces",
    headers=headers,
    json={"name": "Acme Agent Workspace", "slug": "acme-agent-workspace"},
).json()["workspace"]
 
customer_slack = httpx.post(
    f"https://api.weavz.io/api/v1/workspaces/{workspace['id']}/integrations",
    headers=headers,
    json={
        "integrationName": "slack",
        "alias": "customer_slack",
        "connectionStrategy": "per_user",
        "enabledActions": ["send_channel_message", "list_channels"],
    },
).json()["integration"]
 
for integration in [
    {
        "integrationName": "storage",
        "alias": "files",
        "settings": {"persistence": {"scope": "workspace"}},
    },
    {
        "integrationName": "kv-store",
        "alias": "state",
        "settings": {"persistence": {"scope": "workspace"}},
    },
    {"integrationName": "agent-browser", "alias": "browser"},
]:
    httpx.post(
        f"https://api.weavz.io/api/v1/workspaces/{workspace['id']}/integrations",
        headers=headers,
        json=integration,
    )

2. Register the user and start hosted auth

End users are how Weavz maps your application's users to per-user credentials and state. For a per_user workspace integration, create the end user first, then create a connect URL for the configured workspace integration.

bash

curl -X POST https://api.weavz.io/api/v1/end-users \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "YOUR_WORKSPACE_ID",
    "externalId": "user_456",
    "displayName": "Alice Johnson"
  }'
 
curl -X POST https://api.weavz.io/api/v1/end-users/END_USER_ID/connect-token \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "workspaceIntegrationId": "CUSTOMER_SLACK_WORKSPACE_INTEGRATION_ID" }'

typescript

const { endUser } = await client.endUsers.create({
  workspaceId: workspace.id,
  externalId: 'user_456',
  displayName: 'Alice Johnson',
})
 
const { connectUrl } = await client.endUsers.createConnectToken(endUser.id, {
  workspaceIntegrationId: customerSlack.id,
})

python

end_user = client.end_users.create(
    workspace_id=workspace["id"],
    external_id="user_456",
    display_name="Alice Johnson",
)["endUser"]
 
connect = client.end_users.create_connect_token(
    end_user["id"],
    workspace_integration_id=customer_slack["id"],
)
connect_url = connect["connectUrl"]

typescript

const endUserRes = await fetch('https://api.weavz.io/api/v1/end-users', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    workspaceId: workspace.id,
    externalId: 'user_456',
    displayName: 'Alice Johnson',
  }),
})
const { endUser } = await endUserRes.json()
 
const connectRes = await fetch(`https://api.weavz.io/api/v1/end-users/${endUser.id}/connect-token`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ workspaceIntegrationId: customerSlack.id }),
})
const { connectUrl } = await connectRes.json()

python

end_user = httpx.post(
    "https://api.weavz.io/api/v1/end-users",
    headers=headers,
    json={
        "workspaceId": workspace["id"],
        "externalId": "user_456",
        "displayName": "Alice Johnson",
    },
).json()["endUser"]
 
connect_url = httpx.post(
    f"https://api.weavz.io/api/v1/end-users/{end_user['id']}/connect-token",
    headers=headers,
    json={"workspaceIntegrationId": customer_slack["id"]},
).json()["connectUrl"]

Open connectUrl for the user. After authorization, the customer_slack workspace integration can resolve that user's Slack connection whenever an MCP call includes the same end-user context.

3. Create the MCP server and token

Use Code Mode for broad agent workspaces. Use OAuth for interactive hosted clients. Use a per-end-user bearer token when your application owns the agent harness and needs to pass credentials to an MCP client programmatically.

bash

curl -X POST https://api.weavz.io/api/v1/mcp/servers \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Agent Tools",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "mode": "CODE",
    "authMode": "oauth_and_bearer",
    "endUserAccess": "restricted"
  }'
 
curl -X POST https://api.weavz.io/api/v1/mcp/servers/MCP_SERVER_ID/access-tokens \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "endUserId": "END_USER_ID",
    "scopes": ["mcp:tools", "mcp:code"],
    "expiresIn": 2592000
  }'

typescript

const { server, mcpEndpoint } = await client.mcpServers.create({
  name: 'Acme Agent Tools',
  workspaceId: workspace.id,
  mode: 'CODE',
  authMode: 'oauth_and_bearer',
  endUserAccess: 'restricted',
})
 
const { bearerToken } = await client.mcpServers.createBearerToken(server.id, {
  endUserId: endUser.id,
  scopes: ['mcp:tools', 'mcp:code'],
  expiresIn: 60 * 60 * 24 * 30,
})

python

mcp = client.mcp_servers.create(
    name="Acme Agent Tools",
    workspace_id=workspace["id"],
    mode="CODE",
    auth_mode="oauth_and_bearer",
    end_user_access="restricted",
)
 
token = client.mcp_servers.create_bearer_token(
    mcp["server"]["id"],
    end_user_id=end_user["id"],
    scopes=["mcp:tools", "mcp:code"],
    expires_in=60 * 60 * 24 * 30,
)
 
mcp_endpoint = mcp["mcpEndpoint"]
bearer_token = token["bearerToken"]

typescript

const mcpRes = await fetch('https://api.weavz.io/api/v1/mcp/servers', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'Acme Agent Tools',
    workspaceId: workspace.id,
    mode: 'CODE',
    authMode: 'oauth_and_bearer',
    endUserAccess: 'restricted',
  }),
})
const { server, mcpEndpoint } = await mcpRes.json()
 
const tokenRes = await fetch(`https://api.weavz.io/api/v1/mcp/servers/${server.id}/access-tokens`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    endUserId: endUser.id,
    scopes: ['mcp:tools', 'mcp:code'],
    expiresIn: 60 * 60 * 24 * 30,
  }),
})
const { bearerToken } = await tokenRes.json()

python

mcp = httpx.post(
    "https://api.weavz.io/api/v1/mcp/servers",
    headers=headers,
    json={
        "name": "Acme Agent Tools",
        "workspaceId": workspace["id"],
        "mode": "CODE",
        "authMode": "oauth_and_bearer",
        "endUserAccess": "restricted",
    },
).json()
 
token = httpx.post(
    f"https://api.weavz.io/api/v1/mcp/servers/{mcp['server']['id']}/access-tokens",
    headers=headers,
    json={
        "endUserId": end_user["id"],
        "scopes": ["mcp:tools", "mcp:code"],
        "expiresIn": 60 * 60 * 24 * 30,
    },
).json()
 
mcp_endpoint = mcp["mcpEndpoint"]
bearer_token = token["bearerToken"]

Store the mcpEndpoint and bearerToken in your backend and pass them to your agent harness as the MCP server URL and Authorization: Bearer mcp_... header. Do not put your wvz_... API key in an agent client or browser.

4. Plug in the harness

Most MCP clients accept a URL plus headers. The exact config differs by framework, but the shape is:

json

{
  "name": "weavz-acme",
  "url": "https://api.weavz.io/mcp/srv_...",
  "headers": {
    "Authorization": "Bearer mcp_..."
  }
}

Once connected, the agent should use Code Mode:

weavz_search to find customer_slack, files, state, and browser.
weavz_read_api to inspect the actions it plans to call.
weavz_execute to run the workflow against the user's connected accounts and scoped state.

For a hosted client that supports MCP OAuth, do not mint a bearer token. Give the client the mcpEndpoint; the user signs in through Weavz and the MCP token is issued by the OAuth flow.

Where direct actions fit

Direct action execution is still important, but it is not the center of the agent story.

Use POST /api/v1/actions/execute or SDK client.actions.execute() when:

your backend owns the workflow and does not need an MCP client
you are smoke-testing a workspace integration before exposing it to agents
a trigger or queue worker needs to call one action deterministically
your product UI needs a direct, synchronous operation

Use MCP when:

an agent needs to discover tools dynamically
a workflow may combine several integrations, files, browser control, and state
each user should bring their own credentials
your product needs to hand a prepared tool surface to Claude, ChatGPT, Codex, Cursor, or a custom harness