Weavz MCP App

The Weavz MCP App is the fastest way to use a Weavz workspace inside AI clients that support remote MCP connectors. Instead of creating a custom MCP server first, add the Weavz connector URL, sign in, choose the workspace the agent should use, and let Weavz expose the workspace's configured integrations through Code Mode.

Use this guide for Claude, ChatGPT, Codex, Cursor, Claude Code, and other MCP-compatible agents when the user experience should stay inside the AI client as much as possible.

Connector URL

Use your Weavz platform URL plus /mcp/weavz.

https://platform.weavz.io/mcp/weavz

For self-hosted or private deployments, replace the host with your public Weavz API host:

https://your-weavz-domain.example.com/mcp/weavz

The endpoint must be reachable by the MCP client over HTTPS. Hosted clients such as Claude and ChatGPT connect from their own cloud infrastructure, so a connector URL that only works from your laptop, VPN, or private office network will not work unless the client provides a tunnel or your network allows that traffic.

Fast Client Setup

Claude and ChatGPT do not document a stable prefilled remote-MCP install URL that can add an arbitrary custom connector with one click. Use their connector settings screens, then paste the Weavz connector URL. Review Claude's custom connector guide, OpenAI's ChatGPT connection guide, and OpenAI's developer mode guide before publishing setup instructions for your users.

What Users See

1. The user adds the Weavz connector in the MCP client.
2. The client opens Weavz sign-in.
3. If the user belongs to more than one workspace, Weavz asks which workspace this connector should use.
4. Weavz shows the connector authorization screen.
5. The client receives an MCP token scoped to that one workspace.
6. The user can open the Weavz MCP App inside the client to add integrations, connect or reconnect user-owned credentials, refresh status, view pending approvals, and open the dashboard for advanced settings.

If a signed-in user has exactly one workspace, Weavz uses that workspace without showing an extra chooser. If a new user has no workspace yet, Weavz creates a starter workspace named Weavz Agent Workspace with Code Mode, Agent Browser, Agent Browser AI, Filesystem, State KV, memory, scratchpad, web reading, HTTP, transformation, date/time, hash utilities, and common SaaS integrations.

Choose The Right Setup

The Weavz MCP App uses Code Mode by default. Agents get weavz_search, weavz_read_api, and weavz_execute for compact, dynamic use of the selected workspace. The embedded app adds a visual control surface for connection management and status.

The starter workspace exposes deterministic browser tools as weavz.browser. It also exposes Agent Browser AI as weavz.browser_ai; those natural-language browser actions require the user to connect an LLM provider key before they can run.

For browser work, agents should batch several browser operations inside one weavz_execute call, such as snapshot, click, type, evaluate, and screenshot, then return a concise result. Reuse sessionId across separate runs only when the workflow needs human handoff or persistent browser state.

Add To Claude

Claude supports custom remote MCP connectors. For individual plans, add a custom connector from Customize > Connectors. For Team and Enterprise plans, an Owner or Primary Owner adds the connector from organization settings; members then connect it individually.

Claude's remote connector docs note that hosted Claude clients connect to the remote MCP server from Anthropic's infrastructure, not from the user's local device. Review Claude's current custom connector setup guide before submitting or rolling out an organization connector.

Add To ChatGPT

ChatGPT can test remote MCP apps in developer mode, and public distribution uses OpenAI's app submission flow. For private testing, create a connector in ChatGPT settings and use the Weavz MCP App URL.

For public ChatGPT distribution, review OpenAI's current Apps SDK connection guide, authentication guidance, and app submission guidelines.

Add To Coding Agents

Coding agents that support remote HTTP MCP can use the same endpoint. Use OAuth when the client supports browser authorization.

Claude Code setup:

claude mcp add --transport http weavz https://platform.weavz.io/mcp/weavz
claude mcp list

Codex CLI setup:

codex mcp add weavz --url https://platform.weavz.io/mcp/weavz
codex mcp login weavz

Manual Codex config:

[mcp_servers.weavz]
url = "https://platform.weavz.io/mcp/weavz"

Generic MCP config shape:

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

Connect Integrations Inside The App

After the connector is authorized, ask the AI client to open Weavz, or call the app's visible entrypoint from the client tools menu. The embedded app shows:

Admins can configure deeper behavior in the dashboard: workspace integration aliases, connection strategies, enabled actions, input partials, Human Gates, built-in Filesystem/State KV settings, and Sandbox policy. Changes to workspace integrations sync into the connector's MCP server.

Aliases are what agents call. Use purpose-readable names such as office_slack, support_slack_bot, customer_gmail, or billing_stripe; avoid vague names like default, prod, or slack2 when a workspace may contain more than one configured account.

Integrations added from the Weavz MCP App create a workspace integration alias, but their credential session is scoped to the signed-in connector user. This keeps one user's Slack, Gmail, Sheets, or other account separate from another user's account even when they use the same connector workspace. Built-in Filesystem, State KV, and Code Mode state created through the connector default to end-user scope as well. Use the dashboard, SDK, or API when you intentionally want a shared workspace credential or shared workspace state.

Workspace Selection

Workspace selection is intentionally part of the authorization flow.

• A connector token is scoped to one selected workspace.
• A user with more than one workspace chooses during sign-in.
• A user with one workspace skips the chooser.
• A user with no workspace receives a starter workspace.
• To change workspaces, disconnect or reauthorize the connector and choose again.

This keeps tool execution, connection resolution, approvals, and built-in state tied to the selected workspace instead of letting a running chat silently switch context.

Launch Checklist

Before inviting users or submitting the connector to a marketplace:

1. Confirm the connector URL is public, HTTPS, and stable.
2. Verify sign-in works for new users, existing single-workspace users, and existing multi-workspace users.
3. Connect at least one OAuth integration from the embedded app.
4. Confirm Code Mode tools return expected results from the selected workspace.
5. Test a Human Gate approval from the MCP client.
6. Confirm reconnecting lets the user choose a different workspace.
7. Review tool names, descriptions, and workspace integration aliases for clarity.
8. Confirm destructive or sensitive actions have Human Gates or are not enabled.
9. Test in every target client before submitting for public distribution.

Troubleshooting

Related Docs

• MCP Servers
• MCP Code Mode
• MCP Tool Mode
• Using Built-In Workspace Integrations
• Human Gates