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 credentials

Click Create. Copy the bearer token and SSE endpoint — you'll need these to connect your AI client.

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 bearerToken = result.bearerToken
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"]
bearer_token = result["bearerToken"]
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, bearerToken, 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"]
bearer_token = data["bearerToken"]
endpoint = data["mcpEndpoint"]

Response:

json

{
  "server": {
    "id": "mcp_abc123",
    "name": "My AI Agent Tools",
    "mode": "TOOLS"
  },
  "bearerToken": "mcp_token_xyz...",
  "mcpEndpoint": "https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/sse"
}

Add Tools

Each tool maps to one integration action. You can add tools from different integrations to the same server.

Open your MCP server

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

Add a tool

Click Add Tool. Select an integration (e.g. Slack, GitHub) and pick the action you want to expose.

Set a connection

Choose the connection that this tool should use for authentication.

Save

Click Save. The tool is now available to any AI client connected to this server.

bash

# Add Slack messaging
curl -X POST https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/tools \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "actionName": "send_channel_message",
    "connectionId": "conn_slack"
  }'
 
# Add GitHub issue creation
curl -X POST https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/tools \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "github",
    "actionName": "create_issue",
    "connectionId": "conn_github"
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
const serverId = 'mcp_abc123'
 
// Add Slack messaging
await client.mcpServers.addTool(serverId, {
  integrationName: 'slack',
  actionName: 'send_channel_message',
  connectionId: 'conn_slack',
})
 
// Add GitHub issue creation
await client.mcpServers.addTool(serverId, {
  integrationName: 'github',
  actionName: 'create_issue',
  connectionId: 'conn_github',
})
 
// Add Google Sheets reading
await client.mcpServers.addTool(serverId, {
  integrationName: 'google-sheets',
  actionName: 'read_sheet',
  connectionId: 'conn_gsheets',
})

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
server_id = "mcp_abc123"
 
# Add Slack messaging
client.mcp_servers.add_tool(
    server_id,
    integration_name="slack",
    action_name="send_channel_message",
    connection_id="conn_slack",
)
 
# Add GitHub issue creation
client.mcp_servers.add_tool(
    server_id,
    integration_name="github",
    action_name="create_issue",
    connection_id="conn_github",
)
 
# Add Google Sheets reading
client.mcp_servers.add_tool(
    server_id,
    integration_name="google-sheets",
    action_name="read_sheet",
    connection_id="conn_gsheets",
)

typescript

const headers = {
  'Authorization': 'Bearer wvz_your_api_key',
  'Content-Type': 'application/json',
}
 
// Add Slack messaging
await fetch('https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/tools', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    integrationName: 'slack',
    actionName: 'send_channel_message',
    connectionId: 'conn_slack',
  }),
})
 
// Add GitHub issue creation
await fetch('https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/tools', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    integrationName: 'github',
    actionName: 'create_issue',
    connectionId: 'conn_github',
  }),
})

python

import httpx
 
headers = {"Authorization": "Bearer wvz_your_api_key"}
 
# Add Slack messaging
httpx.post(
    "https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/tools",
    headers=headers,
    json={
        "integrationName": "slack",
        "actionName": "send_channel_message",
        "connectionId": "conn_slack",
    },
)
 
# Add GitHub issue creation
httpx.post(
    "https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/tools",
    headers=headers,
    json={
        "integrationName": "github",
        "actionName": "create_issue",
        "connectionId": "conn_github",
    },
)

Tool Naming Convention

Tools are automatically named using the pattern {integrationAlias}__{actionName}:

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 SSE endpoint and bearer token from the server creation step.

Add to your Claude Desktop config (claude_desktop_config.json):

json

{
  "mcpServers": {
    "weavz": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/sse",
        "--header",
        "Authorization:Bearer mcp_token_xyz..."
      ]
    }
  }
}

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

json

{
  "mcpServers": {
    "weavz": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/sse",
        "--header",
        "Authorization:Bearer mcp_token_xyz..."
      ]
    }
  }
}

bash

claude mcp add weavz \
  --transport sse \
  https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/sse \
  --header "Authorization:Bearer mcp_token_xyz..."

Managing Tools

bash

curl -X PATCH https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/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/mcp_abc123/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/mcp_abc123/regenerate-token \
  -H "Authorization: Bearer wvz_your_api_key"

You can scope an MCP server to a specific end user by passing endUserId when creating the server. The server will resolve connections belonging to that end user, so an AI agent automatically uses their connected accounts.

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": "User Agent",
    "workspaceId": "proj_abc123",
    "endUserId": "user_123",
    "mode": "TOOLS"
  }'

typescript

const { server, bearerToken } = await client.mcpServers.create({
  name: 'User Agent',
  workspaceId: 'proj_abc123',
  endUserId: 'user_123',
  mode: 'TOOLS',
})

python

result = client.mcp_servers.create(
    name="User Agent",
    workspace_id="proj_abc123",
    end_user_id="user_123",
    mode="TOOLS",
)

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: 'User Agent',
    workspaceId: 'proj_abc123',
    endUserId: 'user_123',
    mode: 'TOOLS',
  }),
})
const data = 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": "User Agent",
        "workspaceId": "proj_abc123",
        "endUserId": "user_123",
        "mode": "TOOLS",
    },
)
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.

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.