MCP Servers

Expose integrations as tools for AI agents via the Model Context Protocol.

MCP Servers

MCP (Model Context Protocol) servers expose your integrations as tools that AI agents can discover and use. Create an MCP server, add integration tools, and connect it to Claude Desktop, Cursor, or any MCP-compatible client.

Server Modes

MCP servers operate in one of two modes:

TOOLS Mode

Each integration action is exposed as a separate tool. The AI agent sees a flat list of tools like slack__send_channel_message, github__create_issue, etc. Best for focused servers with a small number of integrations.

CODE Mode

Instead of individual tools, the server exposes three meta-tools:

Tool	Purpose
`weavz_search`	Search available integrations, actions, and their schemas
`weavz_read_api`	Read detailed API documentation for a specific action
`weavz_execute`	Execute code that calls integration actions

CODE mode dramatically reduces context usage (80-98% less) by letting the AI agent discover and call actions dynamically through code, rather than loading all tool schemas upfront. Best for servers with many integrations.

Creating an MCP Server

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 Tools",
    "workspaceId": "proj_abc123",
    "mode": "TOOLS"
  }'

typescript

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

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.mcp_servers.create(
    name="My AI Tools",
    workspace_id="proj_abc123",
    mode="TOOLS",
)
server = result["server"]
bearer_token = result["bearerToken"]
mcp_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 Tools',
    workspaceId: 'proj_abc123',
    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": "My AI Tools",
        "workspaceId": "proj_abc123",
        "mode": "TOOLS",
    },
)
data = res.json()

The response includes the server's SSE endpoint and bearer token:

json

{
  "id": "mcp_abc123",
  "name": "My AI Tools",
  "mode": "TOOLS",
  "endpoint": "https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/protocol",
  "bearerToken": "mcp_xxxxxxxxxxxxxxxx"
}

Adding Tools

Add integration actions as tools on your MCP server:

bash

curl -X POST https://api.weavz.io/api/v1/mcp/servers/{serverId}/tools \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "actionName": "send_channel_message",
    "connectionId": "conn_abc123"
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { tool } = await client.mcpServers.addTool('mcp_abc123', {
  integrationName: 'slack',
  actionName: 'send_channel_message',
  connectionId: 'conn_abc123',
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.mcp_servers.add_tool("mcp_abc123",
    integration_name="slack",
    action_name="send_channel_message",
    connection_id="conn_abc123",
)
tool = result["tool"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/tools', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'slack',
    actionName: 'send_channel_message',
    connectionId: 'conn_abc123',
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/tools",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "slack",
        "actionName": "send_channel_message",
        "connectionId": "conn_abc123",
    },
)
data = res.json()

Each API call adds one tool. To add multiple tools, make separate requests for each action.

Tool Naming

In TOOLS mode, tools are named using the pattern {integrationName}__{actionName}:

slack__send_channel_message
github__create_issue
google_sheets__read_rows

Integration Aliases

You can register the same integration multiple times under different aliases. This is useful when you need separate connections for the same service (e.g., a bot Slack connection and a user Slack connection):

bash

curl -X POST https://api.weavz.io/api/v1/mcp/servers/{serverId}/tools \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "integrationAlias": "slack_bot",
    "actionName": "send_channel_message",
    "connectionId": "conn_bot"
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { tool } = await client.mcpServers.addTool('mcp_abc123', {
  integrationName: 'slack',
  integrationAlias: 'slack_bot',
  actionName: 'send_channel_message',
  connectionId: 'conn_bot',
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.mcp_servers.add_tool("mcp_abc123",
    integration_name="slack",
    integration_alias="slack_bot",
    action_name="send_channel_message",
    connection_id="conn_bot",
)
tool = result["tool"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/tools', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'slack',
    integrationAlias: 'slack_bot',
    actionName: 'send_channel_message',
    connectionId: 'conn_bot',
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/tools",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "slack",
        "integrationAlias": "slack_bot",
        "actionName": "send_channel_message",
        "connectionId": "conn_bot",
    },
)
data = res.json()

This creates tools named slack_bot__send_channel_message instead of slack__send_channel_message. Each alias can have its own connection and action subset.

Alias format: lowercase letters, numbers, hyphens, and underscores. Must start with a letter, max 64 characters.

Helper Tools

For actions with select inputs (e.g., selecting a Slack channel), MCP servers auto-generate companion tools so the AI agent can discover valid values:

slack__list_channels   →  companion tool for the "channel" select input

Helper tool naming: {integrationAlias}__list_{propertyName}s

Input Partials

Input partials let you assign saved parameter presets to MCP tools. When a partial is assigned, its values are merged into the tool's input at execution time. Enforced keys are locked and cannot be overridden by the AI agent — they are also stripped from the tool's schema so the agent never sees them.

bash

curl -X POST https://api.weavz.io/api/v1/mcp/servers/{serverId}/tools \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "actionName": "send_channel_message",
    "connectionId": "conn_abc123",
    "partialIds": ["partial_001", "partial_002"]
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { tool } = await client.mcpServers.addTool('mcp_abc123', {
  integrationName: 'slack',
  actionName: 'send_channel_message',
  connectionId: 'conn_abc123',
  partialIds: ['partial_001', 'partial_002'],
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.mcp_servers.add_tool("mcp_abc123",
    integration_name="slack",
    action_name="send_channel_message",
    connection_id="conn_abc123",
    partial_ids=["partial_001", "partial_002"],
)
tool = result["tool"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/tools', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'slack',
    actionName: 'send_channel_message',
    connectionId: 'conn_abc123',
    partialIds: ['partial_001', 'partial_002'],
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/tools",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "slack",
        "actionName": "send_channel_message",
        "connectionId": "conn_abc123",
        "partialIds": ["partial_001", "partial_002"],
    },
)
data = res.json()

Connecting AI Clients

Claude Desktop

Add to your claude_desktop_config.json:

json

{
  "mcpServers": {
    "weavz": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.weavz.io/api/v1/mcp/servers/{serverId}/protocol",
        "--header",
        "Authorization: Bearer mcp_your_bearer_token"
      ]
    }
  }
}

Cursor

Add to your Cursor MCP settings:

json

{
  "mcpServers": {
    "weavz": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.weavz.io/api/v1/mcp/servers/{serverId}/protocol",
        "--header",
        "Authorization: Bearer mcp_your_bearer_token"
      ]
    }
  }
}

Any MCP Client

The MCP server endpoint supports Server-Sent Events (SSE) transport. Connect using:

Endpoint: https://api.weavz.io/api/v1/mcp/servers/{serverId}/protocol
Auth: Authorization: Bearer mcp_your_bearer_token

Managing Tools

List tools on a server

bash

curl https://api.weavz.io/api/v1/mcp/servers/{serverId}/tools \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { server, tools } = await client.mcpServers.get('mcp_abc123')

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.mcp_servers.get("mcp_abc123")
tools = result["tools"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/mcp_abc123', {
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
  },
})
const data = await res.json()

python

import httpx
res = httpx.get(
    "https://api.weavz.io/api/v1/mcp/servers/mcp_abc123",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()

Remove a tool

bash

curl -X DELETE https://api.weavz.io/api/v1/mcp/servers/{serverId}/tools/{toolId} \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
await client.mcpServers.deleteTool('mcp_abc123', 'tool_xyz')

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
client.mcp_servers.delete_tool("mcp_abc123", "tool_xyz")

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/tools/tool_xyz', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
  },
})
const data = await res.json()

python

import httpx
res = httpx.delete(
    "https://api.weavz.io/api/v1/mcp/servers/mcp_abc123/tools/tool_xyz",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()

End-User MCP Servers

SaaS developers can create MCP servers scoped to a specific end user. The server resolves connections belonging to that end user, so an AI agent operating on their behalf automatically uses their connected accounts.

Pass endUserId when creating the server:

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

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { server, bearerToken, mcpEndpoint } = await client.mcpServers.create({
  name: 'User Agent',
  workspaceId: 'proj_abc123',
  endUserId: 'user_123',
  mode: 'TOOLS',
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.mcp_servers.create(
    name="User Agent",
    workspace_id="proj_abc123",
    end_user_id="user_123",
    mode="TOOLS",
)
server = result["server"]
bearer_token = result["bearerToken"]

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 response includes a setup URL. Share this URL with the end user so they can connect their account and retry.

Next Steps

Actions — understand the actions that MCP tools wrap
Integrations — browse available integrations
Storage & KV Store — use built-in persistence
End Users — learn about the unified identity model

Create your first MCP server in the dashboard or follow the MCP Tool Mode guide.