MCP Server Mode

What MCP Server Mode Is

allv can expose workspace tools and read-only memory as a stateless Streamable HTTP MCP server from the SaaS API. Compatible clients connect to one workspace endpoint and operate in the context of one explicitly selected workspace member.

• check_circleUse MCP Server Mode when your client already speaks the Model Context Protocol.
• check_circleExpect tools from the allv default tool registry plus fixed read-only memory resources.
• check_circleKeep memory writes inside tools such as `agent.update_memory`; MCP resources remain read-only views.

Endpoint and Transport

Endpoint

https://agent.allv.ai/api/workspaces/<workspaceId>/mcp

Transport

Streamable HTTP

Preferred method

POST

Session model

Stateless per request

https://agent.allv.ai/api/workspaces/<workspaceId>/mcp

The MCP server lives on the SaaS API. Workspace tools and memory are resolved fresh for each request rather than through a long-lived server-side session.

Enablement and Auth

1. 1

   Enable MCP server mode

   Turn on the workspace feature flag `mcp_server_v1` in Settings before connecting external clients.

2. 2

   Create a workspace API key

   Open Settings > API Keys, create a named key, and store it in your secret manager or environment variables.

3. 3

   Authenticate the request

   Send the key with `Authorization: Bearer sk_live_...` or `x-api-key: sk_live_...`.

4. 4

   Select the workspace member

   Send either `x-allv-user-id` or `x-allv-user-email` so tool execution and memory reads run in the correct member context.

Tools and Read-only Memory Resources

allv exposes tools directly from the default tool registry. Tool definitions include provider family, approval hints, and permission hints, while execution uses the existing allv tool runtime with the selected workspace member context.

• allv://memory/user/fact
• allv://memory/user/preference
• allv://memory/user/goal
• allv://memory/user/workflow-context
• allv://memory/agent/fact
• allv://memory/agent/preference
• allv://memory/agent/goal
• allv://memory/agent/workflow-context

These resources are read-only. To change memory, call tools such as `agent.update_memory` or `agent.delete_memory`, then read the resource again to confirm the new state.

Easy Examples

Start with a direct SDK client or a Cursor project config. Both use the same workspace endpoint and the same two auth requirements: a workspace API key and an explicit selected-user header.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://agent.allv.ai/api/workspaces/<workspaceId>/mcp"),
  {
    requestInit: {
      headers: {
        Authorization: "Bearer sk_live_...",
        "x-allv-user-email": "user@example.com",
      },
    },
  },
);

const client = new Client({ name: "example-client", version: "1.0.0" });
await client.connect(transport);
await client.listTools();
await client.listResources();

{
  "mcpServers": {
    "allv-production": {
      "url": "https://agent.allv.ai/api/workspaces/<workspaceId>/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ALLV_API_KEY}",
        "x-allv-user-email": "${env:ALLV_USER_EMAIL}"
      }
    }
  }
}

const connections = await client.callTool({ name: "agent.list_connections", arguments: {} });

const before = await client.readResource({ uri: "allv://memory/user/fact" });
await client.callTool({
  name: "agent.update_memory",
  arguments: {
    category: "fact",
    key: "follow_up_style",
    value: "Lead with blockers, then owner updates.",
    scope: "user",
  },
});
const after = await client.readResource({ uri: "allv://memory/user/fact" });

Client Compatibility and v1 Limits

• Cursor is the primary production-ready example for v1 because it can set custom remote MCP headers through `mcp.json`.
• Claude Desktop remote connector support is not yet plug-and-play under the current auth model because v1 requires custom headers plus explicit user selection.
• v1 does not support SSE transport, MCP prompts, MCP resource writes, or user-bound API key auth.

Operational Events

• mcp.request
• mcp.tool_called
• mcp.resource_read
• mcp.auth_failed
• mcp.error

These events make MCP usage auditable alongside the rest of the workspace activity history.