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.
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, 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, andbrowser. - 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.
- Use the Code Mode endpoint included with the MCP Workspace. No separate server creation is needed.
- For hosted MCP clients, use MCP OAuth. For app-owned agent harnesses, issue a private workspace access token for the external end user.
- Plug
mcpEndpointand the returnedaccessTokeninto 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_slackas a per-user Slack integrationfilesfor workspace filesstatefor workspace key-value statebrowserfor hosted browser control
curl -X POST https://platform.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://platform.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://platform.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://platform.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://platform.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" }'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.
curl -X POST https://platform.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://platform.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" }'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. Issue private MCP access
Each MCP Workspace includes one endpoint. Keep Code Mode and OAuth defaults for the common flow; no separate server configuration is needed. Issue access for the external user registered above:
const { accessToken, mcpEndpoint } = await client.mcpWorkspaces.createAccessToken(workspace.id, {
endUserId: endUser.externalId,
scopes: ['mcp:tools', 'mcp:code'], expiresIn: 3600,
})access = client.mcp_workspaces.create_access_token(
workspace["id"], end_user_id=end_user["externalId"],
scopes=["mcp:tools", "mcp:code"], expires_in=3600,
)
mcp_endpoint = access["mcpEndpoint"]
access_token = access["accessToken"]The REST equivalent is POST /api/v1/workspaces/{id}/access-tokens with endUserId set to your application's external user ID. Store the returned URL and token privately and provision them only to that user's agent. Send the token as Authorization: Bearer to the MCP URL; do not send your wvz_ API key to an agent client or frontend.
4. Plug in the harness
Most MCP clients accept a URL plus headers. The exact config differs by framework, but the shape is:
{
"name": "weavz-acme",
"url": "https://platform.weavz.io/mcp/srv_...",
"headers": {
"Authorization": "Bearer YOUR_PRIVATE_MCP_ACCESS_TOKEN"
}
}Once connected, the agent should use Code Mode:
weavz_searchto findcustomer_slack,files,state, andbrowser.weavz_read_apito inspect the actions it plans to call.weavz_executeto 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
What to read next
- Quick Start — a short Slack-to-MCP walkthrough
- Managing End Users — per-user identity and connect URLs
- Using Built-In Workspace Integrations — Filesystem, State KV, browser, HTTP, memory, and Sandbox tools
- MCP Code Mode — the recommended MCP mode for broad agent workspaces
- MCP Servers API — server creation, OAuth, bearer tokens, and Code Mode execution