Quick Start

Connect Slack, send a message, and serve MCP tools quickly.

This guide walks you through connecting Slack, adding it to a workspace, creating an MCP server, and connecting an AI client. It includes a direct action execution smoke test, but the main path is the MCP server your agents will use.

Want the fastest path? Open Templates in the dashboard and choose a starter pack. Templates create a workspace, add per-user integrations, and can create an OAuth CODE-mode MCP server in one flow.

Building an app-owned agent harness? Use the AI-Native SaaS Path after this walkthrough. It covers end-user auth, MCP bearer tokens, and the production provisioning loop.

Before using the setup in production, test it in Playground and add a Human Gates policy for actions that send external messages, change customer data, spend money, or use end-user credentials.

Choose the connection model

Most production apps use workspace integrations as the stable layer and let the connection strategy decide whose credentials are used at runtime.

Model	Use when	Runtime selector
Fixed/shared connection	One bot, team account, or service credential should serve the whole workspace	`workspaceId` + `integrationAlias`
Per-user connection	Each signed-in user must act through their own connected account	`workspaceId` + `integrationAlias` + `endUserId`
Per-user with fallback	Use a user's account when connected, otherwise fall back to a shared account	`workspaceId` + `integrationAlias` + optional `endUserId`
Direct connection external ID	Your backend needs to target one specific credential set outside the workspace integration strategy	`workspaceId` + `connectionExternalId`

This quick start uses a simple shared Slack connection first. For customer-facing agents, read Managing End Users after the first loop and switch the workspace integration to per_user or per_user_with_fallback.

Prerequisites

A Weavz account with an API key (Installation)
A Slack workspace you can connect (Weavz provides the OAuth app — no setup needed)

Create a Workspace

Workspaces scope your integrations, connections, and MCP servers. Create one to get started.

Navigate to Workspaces in the sidebar
Click Create Workspace
Enter the name "My Workspace" and slug my-workspace
Click Create

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": "My Workspace",
    "slug": "my-workspace"
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { workspace } = await client.workspaces.create({
  name: 'My Workspace',
  slug: 'my-workspace',
})
 
console.log(`Workspace created: ${workspace.id}`)

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.workspaces.create(name="My Workspace", slug="my-workspace")
workspace = result["workspace"]
 
print(f"Workspace created: {workspace['id']}")

typescript

const res = await fetch('https://api.weavz.io/api/v1/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'My Workspace', slug: 'my-workspace' }),
})
 
const { workspace } = await res.json()
console.log(`Workspace created: ${workspace.id}`)

python

import httpx
 
res = httpx.post(
    "https://api.weavz.io/api/v1/workspaces",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={"name": "My Workspace", "slug": "my-workspace"},
)
 
workspace = res.json()["workspace"]
print(f"Workspace created: {workspace['id']}")

Connect Slack

Weavz provides platform OAuth apps for services like Slack, so you don't need to create your own. Just open the hosted connect popup, log in to Slack, and authorize.

Open your workspace and go to the Connections tab
Click Create Connection
Select Slack from the integration picker
Click Authorize — a popup opens with Slack's consent screen
Approve access — the popup closes and your connection appears in the list

bash

# Create a connect token
curl -X POST https://api.weavz.io/api/v1/connect/token \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "connectionName": "My Slack",
    "externalId": "my_slack",
    "workspaceId": "YOUR_WORKSPACE_ID"
  }'

The response contains token, connectUrl, and expiresAt. Open the connectUrl in a browser popup to complete authorization, then poll the session token until status is COMPLETED and the response includes connectionId.

bash

curl -X POST https://api.weavz.io/api/v1/connect/session/poll \
  -H "Content-Type: application/json" \
  -d '{ "token": "cst_..." }'

typescript

// Step 1: Create a connect session
const session = await client.connect.createToken({
  integrationName: 'slack',
  connectionName: 'My Slack',
  externalId: 'my_slack',
  workspaceId: workspace.id,
})
 
// Step 2: Open the popup
const result = await client.connect.popup({
  token: session.token,
  connectUrl: session.connectUrl,
})
 
console.log(`Connected: ${result.connectionId}`)

python

# Create a connect token (open connectUrl in a browser)
result = client.connect.create_token(
    integration_name="slack",
    connection_name="My Slack",
    external_id="my_slack",
    workspace_id=workspace["id"],
)
# result contains: token, connectUrl, expiresAt
 
print(f"Open this URL to authorize: {result['connectUrl']}")
# Open result["connectUrl"] in a browser popup
 
completed = client.connect.wait(result["token"])
connection_id = completed["connectionId"]

typescript

// Create a connect token
const res = await fetch('https://api.weavz.io/api/v1/connect/token', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'slack',
    connectionName: 'My Slack',
    externalId: 'my_slack',
    workspaceId: 'YOUR_WORKSPACE_ID',
  }),
})
 
const { token, connectUrl } = await res.json()
// Open connectUrl in a browser popup to complete authorization
 
let connectionId: string | undefined
for (let attempt = 0; attempt < 60; attempt += 1) {
  const pollRes = await fetch('https://api.weavz.io/api/v1/connect/session/poll', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token }),
  })
  const session = await pollRes.json()
  if (session.status === 'COMPLETED') {
    connectionId = session.connectionId
    break
  }
  if (session.status === 'FAILED') throw new Error(session.error || 'Connect failed')
  await new Promise(resolve => setTimeout(resolve, 1000))
}
if (!connectionId) throw new Error('Connect timed out')

python

import httpx
import time
 
res = httpx.post(
    "https://api.weavz.io/api/v1/connect/token",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "slack",
        "connectionName": "My Slack",
        "externalId": "my_slack",
        "workspaceId": "YOUR_WORKSPACE_ID",
    },
)
 
data = res.json()
print(f"Open this URL to authorize: {data['connectUrl']}")
 
connection_id = None
for _ in range(60):
    poll = httpx.post(
        "https://api.weavz.io/api/v1/connect/session/poll",
        json={"token": data["token"]},
    )
    session = poll.json()
    if session["status"] == "COMPLETED":
        connection_id = session["connectionId"]
        break
    if session["status"] == "FAILED":
        raise RuntimeError(session.get("error", "Connect failed"))
    time.sleep(1)
 
if connection_id is None:
    raise TimeoutError("Connect timed out")

Add Slack to the Workspace

Register the connected Slack account as a workspace integration. This gives it a stable alias and lets actions, MCP servers, partials, approvals, and Playground use the same workspace-level configuration.

Open your workspace and go to the Integrations tab
Click Add Integration
Select Slack
Set the alias to office_slack
Choose Fixed connection and select the Slack connection you just created
Save the workspace integration

bash

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": "office_slack",
    "connectionStrategy": "fixed",
    "connectionId": "CONNECTION_ID",
    "enabledActions": ["send_channel_message"]
  }'

typescript

await client.workspaces.addIntegration(workspace.id, {
  integrationName: 'slack',
  alias: 'office_slack',
  connectionStrategy: 'fixed',
  connectionId: result.connectionId,
  enabledActions: ['send_channel_message'],
})

python

client.workspaces.add_integration(
    workspace["id"],
    integration_name="slack",
    integration_alias="office_slack",
    connection_strategy="fixed",
    connection_id=connection_id,
    enabled_actions=["send_channel_message"],
)

typescript

await fetch('https://api.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'slack',
    alias: 'office_slack',
    connectionStrategy: 'fixed',
    connectionId,
    enabledActions: ['send_channel_message'],
  }),
})

python

httpx.post(
    "https://api.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "slack",
        "alias": "office_slack",
        "connectionStrategy": "fixed",
        "connectionId": connection_id,
        "enabledActions": ["send_channel_message"],
    },
)

Optional: Smoke Test Direct Execution

Before connecting an AI client, you can smoke test the workspace integration directly. This is useful for validation, but production agent flows should usually continue through the MCP server created in the next step.

Open the Playground from the sidebar
Select your workspace from the dropdown
Pick the Slack integration
Choose the Send Channel Message action
Enter a channel name and message text
Click Execute and view the result

bash

curl -X POST https://api.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "actionName": "send_channel_message",
    "input": {
      "channel": "#general",
      "text": "Hello from Weavz!"
    },
    "workspaceId": "YOUR_WORKSPACE_ID",
    "integrationAlias": "office_slack"
  }'

typescript

const result = await client.actions.execute('slack', 'send_channel_message', {
  input: {
    channel: '#general',
    text: 'Hello from Weavz!',
  },
  workspaceId: workspace.id,
  integrationAlias: 'office_slack',
})
 
if ('approval' in result) {
  console.log('Approval required:', result.approval.id)
} else {
  console.log('Message sent:', result.output)
}

python

result = client.actions.execute(
    "slack",
    "send_channel_message",
    input={"channel": "#general", "text": "Hello from Weavz!"},
    workspace_id=workspace["id"],
    integration_alias="office_slack",
)
 
print("Message sent:", result["output"])

typescript

const res = await fetch('https://api.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'slack',
    actionName: 'send_channel_message',
    input: { channel: '#general', text: 'Hello from Weavz!' },
    workspaceId: 'YOUR_WORKSPACE_ID',
    integrationAlias: 'office_slack',
  }),
})
 
const { output } = await res.json()
console.log('Message sent:', output)

python

res = httpx.post(
    "https://api.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "slack",
        "actionName": "send_channel_message",
        "input": {"channel": "#general", "text": "Hello from Weavz!"},
        "workspaceId": "YOUR_WORKSPACE_ID",
        "integrationAlias": "office_slack",
    },
)
 
print("Message sent:", res.json()["output"])

The response contains the Slack API result:

json

{
  "success": true,
  "output": {
    "ok": true,
    "channel": "C01234567",
    "ts": "1234567890.123456",
    "message": {
      "text": "Hello from Weavz!",
      "type": "message"
    }
  }
}

Create an MCP Server

MCP servers let AI agents use your integrations as tools. Start with Code Mode for agents: it exposes three meta-tools so the agent can search available actions, read typed APIs, and execute multi-step workflows without loading every tool schema upfront.

Navigate to MCP Servers in the sidebar
Click Create Server
Enter the name "My AI Tools", select CODE mode, and pick your workspace
Click Create
Copy the MCP endpoint from the server details. New servers use MCP OAuth by default, and workspace integrations such as office_slack sync automatically.

bash

# Create the MCP server
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": "My AI Tools",
    "mode": "CODE",
    "workspaceId": "YOUR_WORKSPACE_ID"
  }'

The office_slack workspace integration syncs into the MCP server automatically.

typescript

const { mcpEndpoint } = await client.mcpServers.create({
  name: 'My AI Tools',
  mode: 'CODE',
  workspaceId: workspace.id,
})
 
console.log(`MCP endpoint: ${mcpEndpoint}`)

python

result = client.mcp_servers.create(
    name="My AI Tools",
    mode="CODE",
    workspace_id=workspace["id"],
)
 
mcp_endpoint = result["mcpEndpoint"]
 
print(f"MCP endpoint: {mcp_endpoint}")

typescript

const serverRes = await fetch('https://api.weavz.io/api/v1/mcp/servers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'My AI Tools',
    mode: 'CODE',
    workspaceId: 'YOUR_WORKSPACE_ID',
  }),
})
 
const { mcpEndpoint } = await serverRes.json()

python

server_res = httpx.post(
    "https://api.weavz.io/api/v1/mcp/servers",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "name": "My AI Tools",
        "mode": "CODE",
        "workspaceId": "YOUR_WORKSPACE_ID",
    },
)
 
data = server_res.json()
mcp_endpoint = data["mcpEndpoint"]
 
print(f"MCP endpoint: {mcp_endpoint}")

This quick-start uses the minimum useful payload. New servers default to authMode: "oauth", endUserAccess: "restricted", and settings.codeMode.approvalWaitSeconds: 0. For Code Mode approval waits or bearer-provisioned clients, pass optional server fields:

json

{
  "settings": { "codeMode": { "approvalWaitSeconds": 30 } },
  "authMode": "oauth_and_bearer",
  "endUserAccess": "restricted"
}

See MCP Servers for every create field, and MCP Code Mode for the agent-focused setup.

Sandbox execution policy, such as timeout and persistence, is configured on the advanced-code workspace integration, not on the MCP server itself.

Connect an AI Client

Use the MCP server endpoint to connect an OAuth-capable AI client. Weavz handles MCP OAuth sign-in when the client connects.

In Claude, open Customize > Connectors, add a custom connector, and paste the MCP endpoint:

text

https://api.weavz.io/mcp/srv_{serverId}

For Claude Code:

bash

claude mcp add --transport http weavz https://api.weavz.io/mcp/srv_{serverId}

Add to your Cursor MCP settings:

json

{
  "mcpServers": {
    "weavz": {
      "type": "http",
      "url": "https://api.weavz.io/mcp/srv_{serverId}"
    }
  }
}

Add to .vscode/mcp.json:

json

{
  "servers": {
    "weavz": {
      "type": "http",
      "url": "https://api.weavz.io/mcp/srv_{serverId}"
    }
  }
}

Now ask Claude or Cursor to "send a message to #general in Slack" and watch it search, read the Slack API shape, and execute the action through Code Mode.

What's Next

You've connected Slack via OAuth, configured a workspace integration, created a Code Mode MCP server, and connected an AI client. Here's where to go from here:

AI-Native SaaS Path — provision workspaces, end-user auth, MCP servers, and per-user MCP tokens for app-owned agent harnesses
Connections — learn about auth types, multi-tenant scoping, and the hosted connect flow
Actions — explore action execution patterns and input schemas
MCP Servers — configure Code Mode and Tool Mode
Input Partials — save parameter presets and enforce values
Triggers — receive real-time events from integrations
Integrations — browse all 500+ available integrations