MCP Tool Mode

Set up MCP servers in TOOLS mode to expose integration actions as individual tools for AI agents.

TOOLS mode MCP servers expose each integration action as an individual tool. AI agents like Claude, Cursor, and others see every action as a separate callable tool with its own typed input schema.

Create an MCP Server

Navigate to MCP Servers

Open the dashboard and go to MCP Servers in the sidebar.

Create a new server

Click Create MCP Server. Enter a name and optional description.

Select TOOLS mode

Choose TOOLS as the server mode.

Save and copy the endpoint

Click Create. Copy the MCP endpoint. New servers use MCP OAuth by default, so OAuth-capable clients will ask the user to sign in through Weavz when they connect.

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": "My AI Agent Tools",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "mode": "TOOLS"
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const result = await client.mcpServers.create({
  name: 'My AI Agent Tools',
  workspaceId: 'YOUR_WORKSPACE_ID',
  mode: 'TOOLS',
})
 
const serverId = result.server.id
const endpoint = result.mcpEndpoint

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.mcp_servers.create(
    name="My AI Agent Tools",
    workspace_id="YOUR_WORKSPACE_ID",
    mode="TOOLS",
)
 
server_id = result["server"]["id"]
endpoint = result["mcpEndpoint"]

typescript

const res = 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 Agent Tools',
    workspaceId: 'YOUR_WORKSPACE_ID',
    mode: 'TOOLS',
  }),
})
 
const { server, mcpEndpoint } = await res.json()

python

import httpx
 
res = httpx.post(
    "https://api.weavz.io/api/v1/mcp/servers",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "name": "My AI Agent Tools",
        "workspaceId": "YOUR_WORKSPACE_ID",
        "mode": "TOOLS",
    },
)
 
data = res.json()
server_id = data["server"]["id"]
endpoint = data["mcpEndpoint"]

Response:

json

{
  "server": {
    "id": "abc123def456",
    "name": "My AI Agent Tools",
    "mode": "TOOLS",
    "authMode": "oauth",
    "endUserAccess": "restricted"
  },
  "mcpEndpoint": "https://api.weavz.io/mcp/srv_abc123def456"
}

Set authMode to bearer or oauth_and_bearer when you need to provision bearer-authenticated clients. API-created bearer tokens are scoped to one end user; shared static bearer tokens are only returned when the workspace can safely use service-style access.

Add Tools

Tool Mode servers sync tools from the workspace integrations attached to the server's workspace. Add or update workspace integrations first; their alias, connection strategy, enabled actions, and partial defaults determine the normal tool surface. Each synced tool maps to one enabled integration action.

Manual tool creation is available for server-specific overrides, such as exposing one extra action only on a particular MCP server.

Open your MCP server

Go to MCP Servers and click on the server you created.

Check synced tools

Confirm that the workspace integrations you added are visible as tools on the server.

Adjust workspace integrations

If a tool is missing or using the wrong account, update the workspace integration alias, connection strategy, connection, or enabled actions.

Add manual overrides only when needed

Use manual tools when this server needs a smaller or different surface than the workspace default.

Add integrations to the workspace attached to the MCP server. TOOLS mode servers sync enabled workspace integration actions into individual MCP tools automatically.

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": "slack_bot",
    "connectionStrategy": "fixed",
    "connectionId": "9b2b73f7-b575-42b1-9a8f-c233dff5127d",
    "enabledActions": ["send_channel_message"]
  }'
 
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": "github",
    "alias": "github_user",
    "connectionStrategy": "per_user",
    "enabledActions": ["create_issue"]
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
const workspaceId = 'YOUR_WORKSPACE_ID'
 
await client.workspaces.addIntegration(workspaceId, {
  integrationName: 'slack',
  alias: 'slack_bot',
  connectionStrategy: 'fixed',
  connectionId: '9b2b73f7-b575-42b1-9a8f-c233dff5127d',
  enabledActions: ['send_channel_message'],
})
 
await client.workspaces.addIntegration(workspaceId, {
  integrationName: 'github',
  alias: 'github_user',
  connectionStrategy: 'per_user',
  enabledActions: ['create_issue'],
})

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
workspace_id = "YOUR_WORKSPACE_ID"
 
client.workspaces.add_integration(
    workspace_id,
    integration_name="slack",
    integration_alias="slack_bot",
    connection_strategy="fixed",
    connection_id="9b2b73f7-b575-42b1-9a8f-c233dff5127d",
    enabled_actions=["send_channel_message"],
)
 
client.workspaces.add_integration(
    workspace_id,
    integration_name="github",
    integration_alias="github_user",
    connection_strategy="per_user",
    enabled_actions=["create_issue"],
)

typescript

const headers = {
  'Authorization': 'Bearer wvz_your_api_key',
  'Content-Type': 'application/json',
}
const workspaceId = 'YOUR_WORKSPACE_ID'
 
await fetch(`https://api.weavz.io/api/v1/workspaces/${workspaceId}/integrations`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    integrationName: 'slack',
    alias: 'slack_bot',
    connectionStrategy: 'fixed',
    connectionId: '9b2b73f7-b575-42b1-9a8f-c233dff5127d',
    enabledActions: ['send_channel_message'],
  }),
})
 
await fetch(`https://api.weavz.io/api/v1/workspaces/${workspaceId}/integrations`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    integrationName: 'github',
    alias: 'github_user',
    connectionStrategy: 'per_user',
    enabledActions: ['create_issue'],
  }),
})

python

import httpx
 
headers = {"Authorization": "Bearer wvz_your_api_key"}
workspace_id = "YOUR_WORKSPACE_ID"
 
httpx.post(
    f"https://api.weavz.io/api/v1/workspaces/{workspace_id}/integrations",
    headers=headers,
    json={
        "integrationName": "slack",
        "alias": "slack_bot",
        "connectionStrategy": "fixed",
        "connectionId": "9b2b73f7-b575-42b1-9a8f-c233dff5127d",
        "enabledActions": ["send_channel_message"],
    },
)
 
httpx.post(
    f"https://api.weavz.io/api/v1/workspaces/{workspace_id}/integrations",
    headers=headers,
    json={
        "integrationName": "github",
        "alias": "github_user",
        "connectionStrategy": "per_user",
        "enabledActions": ["create_issue"],
    },
)

Manual MCP tool registration is still available through POST /api/v1/mcp/servers/:id/tools when one server needs an override that should not affect the workspace. Use workspace integrations for the normal path so API calls, SDK calls, Playground, and MCP all share the same aliases, connection strategy, enabled actions, partials, and built-in settings.

Tool Naming Convention

Tools are automatically named using the pattern {toolSafeIntegrationAlias}__{actionName}. Hyphens and other non-identifier characters are normalized to underscores:

Integration	Action	Tool Name
`slack`	`send_channel_message`	`slack__send_channel_message`
`github`	`create_issue`	`github__create_issue`
`google-sheets`	`read_sheet`	`google_sheets__read_sheet`

You can register the same integration multiple times under different aliases (e.g. slack_bot, slack_user), each with its own connection. See the Integration Aliases guide.

MCP Helper Tools

For actions with select inputs — like selecting a Slack channel or a GitHub repo — Weavz auto-generates companion tools that let AI agents discover valid values at runtime.

Helper Tool	Purpose
`slack__list_channels`	List available Slack channels
`github__list_repos`	List available GitHub repositories
`google_sheets__list_spreadsheets`	List available spreadsheets

Helper tools are created automatically whenever you add a tool that has dropdown inputs. The AI agent calls them to resolve IDs before executing the main action.

Connect an AI Client

Use the MCP endpoint from the server creation step. OAuth-capable MCP clients can connect with just the endpoint; Weavz handles sign-in and token issuance. If you created a bearer-enabled server, add either an end-user bearer token or a static bearer header as shown below.

In Claude, add a custom connector and paste the MCP endpoint:

text

https://api.weavz.io/mcp/srv_abc123def456

Add to your Cursor MCP settings (.cursor/mcp.json):

json

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

Add to .vscode/mcp.json:

json

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

bash

claude mcp add --transport http weavz https://api.weavz.io/mcp/srv_abc123def456

Only use static bearer for service-style clients that cannot complete MCP OAuth. Create or update the server with authMode: "bearer" or authMode: "oauth_and_bearer", then pass the returned mcp_ token:

json

{
  "mcpServers": {
    "weavz": {
      "type": "http",
      "url": "https://api.weavz.io/mcp/srv_abc123def456",
      "headers": {
        "Authorization": "Bearer mcp_your_static_token"
      }
    }
  }
}

For provisioned clients, create a bearer-enabled server and issue one token per end user:

bash

curl -X POST https://api.weavz.io/api/v1/mcp/servers/abc123def456/access-tokens \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"endUserId": "user_123", "scopes": ["mcp:tools"]}'

Use the returned bearerToken as the Authorization: Bearer mcp_... header.

Managing Tools

bash

curl -X PATCH https://api.weavz.io/api/v1/mcp/servers/abc123def456/tools/tool_xyz \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Send a message to a Slack channel",
    "inputDefaults": { "channel": "C01ABCDEF" }
  }'

bash

curl -X DELETE https://api.weavz.io/api/v1/mcp/servers/abc123def456/tools/tool_xyz \
  -H "Authorization: Bearer wvz_your_api_key"

If a token is compromised, regenerate it and update your AI client config:

bash

curl -X POST https://api.weavz.io/api/v1/mcp/servers/abc123def456/regenerate-token \
  -H "Authorization: Bearer wvz_your_api_key"

This only works for servers whose authMode enables static bearer auth.

End-User MCP Servers

MCP OAuth is the preferred way to resolve per-user integrations when the AI client can complete sign-in: the AI client signs in as the actual user, and all tool calls use that user's connected accounts. For provisioned clients that cannot run OAuth, create a bearer-enabled server and issue one mcp_ bearer token per end user.

You can control who may complete MCP OAuth with endUserAccess:

restricted — only pre-existing workspace end users can authorize. Weavz matches the signed-in user by linked account or email and links the record when needed.
open — any signed-in user can authorize the server; Weavz creates or links their workspace end-user record.

For fully programmatic provisioning on a bearer-enabled server, create an end-user bearer token for an existing end user:

bash

curl -X POST https://api.weavz.io/api/v1/mcp/servers/abc123def456/access-tokens \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "endUserId": "user_123"
  }'

typescript

const { bearerToken, mcpEndpoint } = await client.mcpServers.createBearerToken('abc123def456', {
  endUserId: 'user_123',
})

python

result = client.mcp_servers.create_bearer_token(
    "abc123def456",
    end_user_id="user_123",
)
bearer_token = result["bearerToken"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/abc123def456/access-tokens', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    endUserId: 'user_123',
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://api.weavz.io/api/v1/mcp/servers/abc123def456/access-tokens",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "endUserId": "user_123",
    },
)
data = res.json()

When a tool call fails because the end user hasn't connected the required integration, the error includes a setup URL. Share this URL with the end user — they open it, connect their account, and the agent can retry the tool call.

If a Human Gates policy matches a tool call, the MCP result includes an authenticated approval URL when the policy allows links. Approve it from the Weavz review view or approvals API, then retry the same tool call with the same arguments. See Human Gates.

When to Use TOOLS Mode

TOOLS mode works best when:

You need a small number of focused tools (under 20)
Each tool should be independently callable by the AI agent
You want simple setup without code generation
Your AI agent benefits from seeing all available tools at once

For scenarios with many integrations or where context efficiency matters, consider CODE mode instead.