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, Cursor, ChatGPT, or any MCP-compatible client.

For the fastest end-user setup inside hosted AI clients, use the Weavz MCP App. It uses the generic /mcp/weavz connector URL, signs the user in through Weavz, asks them to choose a workspace when needed, and provisions a Code Mode connector server automatically.

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 office_slack__send_channel_message, support_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 and actions, including compact parameter signatures
`weavz_read_api`	Read detailed TypeScript declarations for one or more integrations or aliases, optionally narrowed to specific actions
`weavz_execute`	Execute code that calls integration actions

CODE mode keeps the initial tool surface small by letting the AI agent discover and call actions dynamically through code, rather than loading all tool schemas upfront. Best for agent-facing servers, broad workspaces, and multi-step workflows that combine several 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": "550e8400-e29b-41d4-a716-446655440000",
    "mode": "CODE"
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { server, mcpEndpoint } = await client.mcpServers.create({
  name: 'My AI Tools',
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  mode: 'CODE',
})

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="550e8400-e29b-41d4-a716-446655440000",
    mode="CODE",
)
server = result["server"]
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: '550e8400-e29b-41d4-a716-446655440000',
    mode: 'CODE',
  }),
})
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": "550e8400-e29b-41d4-a716-446655440000",
        "mode": "CODE",
    },
)
data = res.json()

New MCP servers use OAuth by default. The response includes the MCP endpoint; a one-time bearerToken is returned only if you create the server with authMode: "bearer" or authMode: "oauth_and_bearer".

The examples above intentionally show the minimal create payload. Optional create fields cover advanced setup:

Field	Use when
`settings.codeMode.approvalWaitSeconds`	A Code Mode Human Gate continuation should wait briefly before returning `approval_pending`
`authMode`	You need OAuth, bearer, or both for different MCP client types
`endUserAccess`	You want MCP OAuth to be restricted to pre-added end users or open to new workspace end users
`endUserId`	The server itself should resolve connections for one known end user

See the MCP Servers API reference for the complete request body.

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

json

{
  "server": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My AI Tools",
    "mode": "CODE",
    "authMode": "oauth",
    "endUserAccess": "restricted"
  },
  "mcpEndpoint": "https://api.weavz.io/mcp/srv_550e8400-e29b-41d4-a716-446655440000"
}

Connecting MCP Clients

Use the MCP endpoint with OAuth-capable clients whenever possible. OAuth lets the agent sign in through Weavz so tool calls are scoped to the MCP server, workspace, and end user. Bearer-enabled servers can also issue one mcp_ token per end user for provisioned clients that cannot complete OAuth. Static bearer tokens are reserved for service-style clients that intentionally do not identify a user.

Use the Weavz MCP App when the user should connect directly from Claude, ChatGPT, Codex, Cursor, or another remote MCP client. Use a workspace-specific MCP server endpoint when your product needs a curated server URL or programmatic provisioning.

Client	Recommended setup	Notes
VS Code / GitHub Copilot	One-click `vscode:mcp/install` or `.vscode/mcp.json`	Use `type: "http"` with the MCP endpoint. Enable the server in Copilot Agent mode.
Cursor	One-click Cursor deeplink or `~/.cursor/mcp.json`	Cursor accepts a remote server URL and can authenticate through OAuth.
Claude / Claude Desktop	Add a custom connector with the endpoint	Claude hosted connectors work across Claude surfaces. Claude Desktop `.mcpb` packages are for local desktop extensions, not hosted Weavz endpoints.
Claude Code	`claude mcp add --transport http <name> <endpoint>`	Claude Code opens the browser OAuth flow for compatible remote servers.
ChatGPT	Create a custom MCP app in Developer mode	Availability depends on account and workspace settings. Choose OAuth when configuring the app.
Codex	`codex mcp add <name> --url <endpoint>`	The CLI and IDE extension share the Codex MCP configuration.
Windsurf	Add a remote HTTP MCP in Cascade	Use `serverUrl` or `url` in `~/.codeium/windsurf/mcp_config.json`.
Cline / Kilo Code	Add an HTTP / Streamable HTTP MCP server	Marketplace one-click installs require marketplace listing; workspace-specific Weavz servers should use custom config.
Gemini CLI	`gemini mcp add --transport http <name> <endpoint>`	Verify with `/mcp` after starting Gemini.
OpenCode	Add a remote MCP entry under `mcp` in `opencode.json`	Use `type: "remote"` and `url`.
Manus	Add a custom MCP server from Integrations	Use an end-user bearer token or static bearer only when the client cannot complete OAuth.

Example OAuth config for clients that read mcpServers:

json

{
  "mcpServers": {
    "weavz-sales-tools": {
      "type": "http",
      "url": "https://api.weavz.io/mcp/srv_550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

VS Code uses a slightly different project config shape:

json

{
  "servers": {
    "weavz-sales-tools": {
      "type": "http",
      "url": "https://api.weavz.io/mcp/srv_550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

OpenCode uses a top-level mcp object:

json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "weavz-sales-tools": {
      "type": "remote",
      "url": "https://api.weavz.io/mcp/srv_550e8400-e29b-41d4-a716-446655440000",
      "enabled": true
    }
  }
}

Adding Tools

The default way to expose tools is to add integrations to the workspace. MCP servers attached to that workspace sync workspace integrations automatically, so the same alias, connection strategy, enabled actions, input partial defaults, and built-in persistence settings apply to API, SDK, Playground, and MCP usage.

Use manual MCP tool registration only for server-specific exceptions. Manual tools are useful when one MCP server needs a smaller surface than the workspace default, but they should not be the first model for most setups.

bash

curl -X POST https://api.weavz.io/api/v1/workspaces/{workspaceId}/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "alias": "office_slack",
    "connectionStrategy": "fixed",
    "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "enabledActions": ["send_channel_message"]
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { integration } = await client.workspaces.addIntegration(workspaceId, {
  integrationName: 'slack',
  alias: 'office_slack',
  connectionStrategy: 'fixed',
  connectionId: 'c1d2e3f4-5678-90ab-cdef-1234567890ab',
  enabledActions: ['send_channel_message'],
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.workspaces.add_integration(
    workspace_id,
    integration_name="slack",
    integration_alias="office_slack",
    connection_strategy="fixed",
    connection_id="c1d2e3f4-5678-90ab-cdef-1234567890ab",
    enabled_actions=["send_channel_message"],
)
integration = result["integration"]

typescript

const res = await fetch(`https://api.weavz.io/api/v1/workspaces/${workspaceId}/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: 'c1d2e3f4-5678-90ab-cdef-1234567890ab',
    enabledActions: ['send_channel_message'],
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    f"https://api.weavz.io/api/v1/workspaces/{workspace_id}/integrations",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "slack",
        "alias": "office_slack",
        "connectionStrategy": "fixed",
        "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
        "enabledActions": ["send_channel_message"],
    },
)
data = res.json()

When the same integration is configured more than once, the workspace integration alias becomes the MCP integrationAlias. Tool Mode names synced tools from a tool-safe version of the alias, and Code Mode exposes a JavaScript-safe namespace under weavz. For example, google-sheets becomes google_sheets. Use workspaceIntegrationId when your backend has the exact configured integration UUID.

For advanced server-specific manual tools, use POST /api/v1/mcp/servers/:id/tools and pass integrationAlias when you need a server-local alias override.

When an action input is invalid, MCP calls return a tool error with the validation details. For example, Code Mode reports unknown key "date"; missing required key "dateString" for datetime.parse_date({ date: "..." }), and reports allowed enum values for dropdown fields such as hash.hash({ algorithm: "SHA-256" }).

Tool Naming

In TOOLS mode, synced tools are named using the pattern {toolSafeIntegrationAlias}__{actionName}. Hyphens and other non-identifier characters are normalized to underscores. The alias is agent-facing; the app slug remains visible in the tool description for search and disambiguation:

office_slack__send_channel_message
support_github__create_issue
finance_sheets__read_rows

Advanced Manual Tool Aliases

For most workspaces, configure the same integration multiple times with different workspace integration aliases. MCP tools inherit those aliases automatically.

Use manual MCP tool creation only when one server needs an override that should not affect the workspace integration. In that case, integrationAlias is a server-local tool alias:

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": "office_slack",
    "actionName": "send_channel_message",
    "connectionId": "CONNECTION_UUID"
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { tool } = await client.mcpServers.addTool('550e8400-e29b-41d4-a716-446655440000', {
  integrationName: 'slack',
  integrationAlias: 'office_slack',
  actionName: 'send_channel_message',
  connectionId: 'CONNECTION_UUID',
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.mcp_servers.add_tool("550e8400-e29b-41d4-a716-446655440000",
    integration_name="slack",
    integration_alias="office_slack",
    action_name="send_channel_message",
    connection_id="CONNECTION_UUID",
)
tool = result["tool"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/550e8400-e29b-41d4-a716-446655440000/tools', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'slack',
    integrationAlias: 'office_slack',
    actionName: 'send_channel_message',
    connectionId: 'CONNECTION_UUID',
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://api.weavz.io/api/v1/mcp/servers/550e8400-e29b-41d4-a716-446655440000/tools",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "slack",
        "integrationAlias": "office_slack",
        "actionName": "send_channel_message",
        "connectionId": "CONNECTION_UUID",
    },
)
data = res.json()

This creates a server-specific tool named office_slack__send_channel_message instead of slack__send_channel_message. For shared aliases that should apply across API, SDK, Playground, and MCP, use workspace integrations.

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:

office_slack__send_channel_message__list_channels   →  companion tool for the "channel" select input on the `office_slack` alias

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

Input Partials

Input partials are scoped to a workspace integration alias. Synced MCP tools receive matching default partials automatically, so office_slack__send_channel_message can use partials scoped to office_slack without affecting another Slack alias. Enforced keys are locked and cannot be overridden by the AI agent; they are also stripped from the tool schema so the agent never sees them.

Advanced manual MCP tools can assign explicit partialIds when that server needs a tool-specific preset:

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",
    "integrationAlias": "office_slack",
    "connectionId": "CONNECTION_UUID",
    "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('550e8400-e29b-41d4-a716-446655440000', {
  integrationName: 'slack',
  actionName: 'send_channel_message',
  integrationAlias: 'office_slack',
  connectionId: 'CONNECTION_UUID',
  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("550e8400-e29b-41d4-a716-446655440000",
    integration_name="slack",
    action_name="send_channel_message",
    integration_alias="office_slack",
    connection_id="CONNECTION_UUID",
    partial_ids=["partial_001", "partial_002"],
)
tool = result["tool"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/550e8400-e29b-41d4-a716-446655440000/tools', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'slack',
    actionName: 'send_channel_message',
    integrationAlias: 'office_slack',
    connectionId: 'CONNECTION_UUID',
    partialIds: ['partial_001', 'partial_002'],
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://api.weavz.io/api/v1/mcp/servers/550e8400-e29b-41d4-a716-446655440000/tools",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "slack",
        "actionName": "send_channel_message",
        "integrationAlias": "office_slack",
        "connectionId": "CONNECTION_UUID",
        "partialIds": ["partial_001", "partial_002"],
    },
)
data = res.json()

Managing Tools

List tools on a server

bash

curl https://api.weavz.io/api/v1/mcp/servers/{serverId} \
  -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('550e8400-e29b-41d4-a716-446655440000')

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.mcp_servers.get("550e8400-e29b-41d4-a716-446655440000")
tools = result["tools"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/550e8400-e29b-41d4-a716-446655440000', {
  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/550e8400-e29b-41d4-a716-446655440000",
    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('550e8400-e29b-41d4-a716-446655440000', '660e8400-e29b-41d4-a716-446655440111')

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
client.mcp_servers.delete_tool("550e8400-e29b-41d4-a716-446655440000", "660e8400-e29b-41d4-a716-446655440111")

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/550e8400-e29b-41d4-a716-446655440000/tools/660e8400-e29b-41d4-a716-446655440111', {
  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/550e8400-e29b-41d4-a716-446655440000/tools/660e8400-e29b-41d4-a716-446655440111",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()

End-User MCP Servers

For per-user integrations, prefer MCP OAuth when the MCP client can open a browser sign-in flow. The MCP client signs in as the actual user and Weavz scopes the resulting token to the server, workspace, and end user.

When you provision MCP clients from your own application and already know the end user, create a bearer-enabled MCP server and issue one end-user bearer token per client. These mcp_ tokens are still scoped to the server, workspace, and end user, unlike a shared static bearer token.

Use endUserAccess to control who may authorize the server:

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.

If you are provisioning clients programmatically for a bearer-enabled server, issue an end-user bearer token for an existing end user:

bash

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

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { bearerToken, mcpEndpoint } = await client.mcpServers.createBearerToken('550e8400-e29b-41d4-a716-446655440000', {
  endUserId: 'user_123',
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.mcp_servers.create_bearer_token(
    "550e8400-e29b-41d4-a716-446655440000",
    end_user_id="user_123",
)
bearer_token = result["bearerToken"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/550e8400-e29b-41d4-a716-446655440000/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/550e8400-e29b-41d4-a716-446655440000/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 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
Weavz MCP App — connect Weavz directly from remote MCP clients

Create your first MCP server in the dashboard, start with the MCP Code Mode guide for broad agent access, or use MCP Tool Mode for small focused servers.