Vlozi MCP Architecture Plan

Last Updated: 2026-05-14 Status: Planning — Phase 1 not yet started Owner: Platform Team

This document is the single source of truth for how Vlozi designs, builds, and ships MCP (Model Context Protocol) servers across all products. Read this before writing a single line of MCP code.

1. What is MCP and Why We're Building It

MCP is a standard protocol that lets an AI agent (Claude, Cursor, a customer's autonomous agent) call tools you expose — structured functions with typed inputs and outputs. It's like a REST API, except the caller is an AI, not a browser.

Without MCP, an AI agent working with Vlozi has to navigate our REST APIs raw — it must know URL paths, auth headers, and response shapes. With MCP, the agent calls blog.list_drafts and gets back structured data. The AI doesn't need to know anything about our internals.

Why this matters for Vlozi specifically:

• The AI Brain and Contact Intelligence are only as powerful as the tools available to them. MCP is the connective tissue.
• Customers will want to connect their own AI agents (Claude, GPT, custom) to their Vlozi workspace. MCP is the standard interface.
• Our own dev tooling (Claude Code, Cursor) gets dramatically better when it can call Vlozi tools directly during development.

2. Architecture Decision: Dedicated MCP Gateway

We evaluated three patterns. We are implementing Option D: Dedicated apps/mcp-gateway Worker.

Why Not Option A (Single Central MCP Server)

A single vlozi-mcp package with all tools collapses when we need per-tenant tool filtering — a blog-only customer must not see brain.* tools.

Why Not Option B (Independent Per-Product MCP Servers)

Customers would need to configure N MCP servers in their AI client. Operational overhead is N times higher. Cross-product workflows require the AI to stitch across servers.

Why Not Option C (MCP Inside apps/gateway)

Mixing MCP into the existing REST gateway bloats its bundle with the MCP SDK (~400KB), inflating cold starts for every REST API call — including dashboard requests. MCP traffic (agent-driven, bursty, long-lived SSE connections) has a completely different profile from REST traffic (human-driven, short-lived). A runaway agent loop would compete with dashboard users for the same Worker. An MCP deploy bug could take down the REST gateway. They must be separate.

Option D — What We're Building

REST traffic   →  apps/gateway     →  product workers  (unchanged, stays lean)
MCP traffic    →  apps/mcp-gateway →  product workers  (dedicated, MCP SDK lives here)
 
AI Agent (Claude / Cursor / Customer Agent)
              │
              │  Single MCP connection  (mcp.vlozi.app)
              ▼
┌──────────────────────────────────────────────┐
│            apps/mcp-gateway                   │
│                                               │
│  • Authenticates the caller (API key)         │
│  • Resolves tenant context                    │
│  • Filters tools by subscription plan         │
│  • Routes call to the right product Worker    │
│  • Logs every tool call for audit             │
│  • stdio transport for dev tooling            │
│  • HTTP/SSE transport for production          │
└──────┬───────┬────────┬───────┬──────────────┘
       │       │        │       │
  blog-svc brain-svc  CI-svc  newsletter-svc
 (internal)(internal)(internal)(internal)

apps/mcp-gateway is the only external MCP surface. apps/gateway handles REST only — it never changes for MCP. Both workers share service bindings to the same product Workers and the same KV namespace.

Auth logic is shared via packages/mcp-core — no duplication between the two gateways.

3. Monorepo Structure

packages/
  mcp-core/                   ← NEW: shared MCP types, schema builders, auth helpers
    src/
      types.ts                ← McpTool, McpResource, McpContext interfaces
      schema.ts               ← zod-to-MCP schema converter
      auth.ts                 ← API key validation shared by mcp-gateway and tests
      errors.ts               ← standard MCP error shapes
    package.json
 
apps/
  gateway/                    ← UNCHANGED — REST only, no MCP code ever goes here
 
  mcp-gateway/                ← NEW dedicated MCP Worker
    src/
      index.ts                ← Worker entry point — registers both transports
      server.ts               ← assembles all product tool registries into one MCP server
      router.ts               ← namespace routing: blog.* → BLOG_SERVICE binding
      auth.ts                 ← wraps packages/mcp-core auth + plan-based tool filtering
      transports/
        http-sse.ts           ← production transport (Cloudflare Workers SSE)
        stdio.ts              ← dev transport (local Node.js process)
      resources/
        workspace.ts          ← workspace-level MCP resources
    wrangler.toml             ← service bindings to all product Workers + shared KV
    package.json
 
  blog-service/
    src/
      mcp/                    ← blog MCP tools, co-located with the service
        tools/
          list-posts.ts
          create-draft.ts
          publish-post.ts
          get-analytics.ts
        index.ts              ← exports: { namespace: 'blog', tools: [...] }
 
  brain-service/
    src/
      mcp/
        tools/
          query.ts
          ingest.ts
          list-memories.ts
        index.ts
 
  contact-intelligence/
    src/
      mcp/
        tools/
          search-contacts.ts
          get-contact-memory.ts
          enrich-contact.ts
          log-interaction.ts
        index.ts
 
  newsletter-service/
    src/
      mcp/
        tools/
          list-campaigns.ts
          get-analytics.ts
          create-campaign.ts
        index.ts
 
  content-engine/
    src/
      mcp/                    ← already spec'd in docs/content-engine/mcp-server-spec.md
        tools/
          ...                 ← migrate existing spec into this folder
        index.ts
 
  chat-engine/
    src/
      mcp/
        tools/
          list-sessions.ts
          get-session.ts
        index.ts
 
  media-service/
    src/
      mcp/
        tools/
          upload.ts
          list-assets.ts
          search-assets.ts
        index.ts

Rule: MCP tools live co-located with the service that owns the data. No standalone mcp-server apps. apps/mcp-gateway assembles them — it imports each service's mcp/index.ts registry.

Rule: apps/gateway never imports anything from apps/mcp-gateway and vice versa. They are independent Workers that share only packages/mcp-core.

Problem: apps/mcp-gateway cannot import from service apps (Rule 7.2). Solution: Each service's mcp/index.ts exports only tool descriptors (name, description, schema, handler URL) — no business logic. mcp-gateway proxies the actual execution to the service over the Cloudflare service binding.

4. Tool Descriptor Pattern

Every service exports its MCP tools as descriptors, not live functions. mcp-gateway resolves them.

// apps/blog-service/src/mcp/index.ts
import type { McpToolDescriptor } from '@vlozi/mcp-core'
 
export const namespace = 'blog'
 
export const tools: McpToolDescriptor[] = [
  {
    name: 'list_posts',
    description: 'List blog posts for the current workspace. Supports filtering by status, tag, and date range.',
    inputSchema: {
      type: 'object',
      properties: {
        status: { type: 'string', enum: ['draft', 'published', 'scheduled'], description: 'Filter by post status' },
        limit:  { type: 'number', description: 'Max results (default 20, max 100)' },
        cursor: { type: 'string', description: 'Pagination cursor from previous response' },
      },
    },
    // mcp-gateway calls this internal endpoint when the tool is invoked
    internalRoute: 'GET /mcp/tools/list-posts',
    // PBAC permission required
    requiredPermission: 'blog:posts.read',
    // which plan gates this tool (undefined = all plans)
    requiredPlan: undefined,
  },
  {
    name: 'create_draft',
    description: 'Create a new blog post draft.',
    inputSchema: {
      type: 'object',
      required: ['title'],
      properties: {
        title:   { type: 'string' },
        content: { type: 'string', description: 'MDX content body' },
        tags:    { type: 'array', items: { type: 'string' } },
        slug:    { type: 'string', description: 'URL slug (auto-generated from title if omitted)' },
      },
    },
    internalRoute: 'POST /mcp/tools/create-draft',
    requiredPermission: 'blog:posts.write',
  },
]

The internalRoute is an endpoint the service exposes only to mcp-gateway (verified via x-gateway-key). mcp-gateway receives the MCP call, resolves the descriptor, injects tenant context, and proxies to the service over the service binding.

5. Transport Strategy

5.1 Dev Transport (stdio)

The stdio entrypoint is a plain Node.js script inside apps/mcp-gateway. It runs locally against your dev services — no Cloudflare deployment needed.

Add to root .mcp.json:

{
  "mcpServers": {
    "code-review-graph": {
      "command": "code-review-graph",
      "args": ["serve"],
      "type": "stdio"
    },
    "vlozi": {
      "command": "node",
      "args": ["./apps/mcp-gateway/dist/transports/stdio.js"],
      "type": "stdio",
      "env": {
        "MCP_API_KEY": "${VLOZI_DEV_API_KEY}",
        "MCP_TENANT_ID": "${VLOZI_DEV_TENANT_ID}"
      }
    }
  }
}

Just turbo dev and the MCP server is live. The stdio script connects directly to locally running product services.

5.2 Production Transport (HTTP/SSE)

Endpoint: https://mcp.vlozi.app/sse

This runs inside apps/mcp-gateway on Cloudflare Workers. apps/gateway is not involved. The SSE transport:

1. Client opens a long-lived SSE connection with Authorization: Bearer ls_xxx
2. mcp-gateway authenticates and resolves tenant
3. mcp-gateway streams back the tool list filtered to the tenant's plan
4. Client sends tool calls as POST to https://mcp.vlozi.app/message
5. mcp-gateway proxies to the appropriate product Worker via service binding and streams the result back

Standard MCP SSE transport spec — any MCP-compatible client works out of the box.

6. Authentication & Tenant Resolution

Client sends:  Authorization: Bearer ls_xxx
                             OR
               x-api-key: ls_xxx
 
mcp-gateway (using packages/mcp-core auth):
  1. Validates API key — KV cache first (5min TTL), DB only on miss
  2. Resolves tenantId from key metadata
  3. Loads key's permission scopes
  4. Builds McpContext { tenantId, permissions, plan }
 
Per tool call:
  5. Checks tool.requiredPermission ∈ context.permissions
  6. Checks tool.requiredPlan satisfied by context.plan
  7. If either fails → MCP error: "permission_denied"
  8. Injects x-tenant-id + x-gateway-key into internal service call
  9. Logs: { tenantId, toolName, agentId, durationMs, status }

API keys for MCP are the same ls_ keys used for REST API access — no new auth system. packages/mcp-core/src/auth.ts contains the shared validation logic; apps/gateway and apps/mcp-gateway both import it, so there is no duplication.

Permission Mapping (all products)

7. Full Tool Catalog

7.1 Blog (blog.*)

7.2 AI Brain (brain.*)

7.3 Contact Intelligence (contacts.*)

7.4 Newsletter (newsletter.*)

7.5 Content Engine (content.*)

Full tool spec is in docs/content-engine/mcp-server-spec.md. Summary:

7.6 Media (media.*)

7.7 Chat Engine (chat.*)

Read-only tools for agents to query conversation history and session state.

8. MCP Resources

Resources are read-only context that agents can access without calling a tool. Think of them as live dashboards an agent checks before acting.

9. How to Add a New MCP Tool (Step-by-Step for Devs)

This is the repeatable process every developer follows when adding a tool.

Step 1 — Define the descriptor

In your service's src/mcp/index.ts, add an entry to the tools array:

{
  name: 'my_tool',
  description: 'One sentence — what this does and when an agent should call it.',
  inputSchema: {
    type: 'object',
    required: ['requiredField'],
    properties: {
      requiredField: { type: 'string', description: 'What this field is' },
      optionalField: { type: 'number', description: 'What this field is' },
    },
  },
  internalRoute: 'POST /mcp/tools/my-tool',
  requiredPermission: 'product:resource.action',
}

Step 2 — Implement the internal route handler

In your service, add a Hono route that:

1. Verifies x-gateway-key header
2. Reads x-tenant-id header (never from body)
3. Executes the business logic
4. Returns { data: ..., error: null } on success or { data: null, error: { code, message } } on failure

// apps/blog-service/src/routes/mcp-tools.ts
app.post('/mcp/tools/my-tool', verifyGatewayKey, async (c) => {
  const tenantId = c.req.header('x-tenant-id')!
  const body = await c.req.json()
  // ... business logic ...
  return c.json({ data: result, error: null })
})

Step 3 — Register in the mcp-gateway router

In apps/mcp-gateway/src/router.ts, the service registry auto-discovers tools via the descriptor import. If you added the descriptor in Step 1, mcp-gateway picks it up automatically at next deployment.

Step 4 — Add the permission to your permission matrix

In packages/core-access, add the new permission string to the enum and set which default roles receive it.

Step 5 — Test with the stdio dev server

# Start your service locally
turbo dev --filter=blog-service
 
# In another terminal — run the mcp-gateway stdio server
node apps/mcp-gateway/dist/transports/stdio.js
 
# Claude Code or Cursor now has the tool available

Step 6 — Write a tool test

// apps/blog-service/src/mcp/tools/__tests__/my-tool.test.ts
it('returns posts for valid tenant', async () => {
  const result = await callMcpTool('blog.my_tool', {
    requiredField: 'value',
  }, { tenantId: TEST_TENANT_ID })
  expect(result.error).toBeNull()
  expect(result.data).toBeDefined()
})

10. Rate Limits & Safety Guards

These are non-negotiable and enforced in apps/mcp-gateway/src/auth.ts.

The agentId header is optional for human-initiated calls but required for agent-initiated calls. Agents must self-identify. The gateway rejects bulk write operations from keys without agentId.

11. Implementation Phases

Phase 1 — Dev Tooling Foundation (Target: Week 1)

Goal: Claude Code and Cursor can call Vlozi tools during development. Zero customer impact.

Deliverables:

• packages/mcp-core — shared types: McpToolDescriptor, McpContext, McpError, shared auth util
• apps/mcp-gateway scaffold — wrangler.toml, package.json, tsconfig.json
• apps/mcp-gateway/src/server.ts — MCP server skeleton
• apps/mcp-gateway/src/auth.ts — API key → McpContext resolution (uses mcp-core)
• apps/mcp-gateway/src/router.ts — namespace routing skeleton
• apps/mcp-gateway/src/transports/stdio.ts — stdio transport for local dev
• Blog service MCP descriptors + internal route handlers (all 9 tools)
• Brain service MCP descriptors + internal route handlers (all 5 tools)
• Updated .mcp.json with vlozi stdio server entry
• Dev setup guide in this file (Section 12)

Done when: A developer can open Claude Code and ask "list my blog drafts" and get a real response.

Phase 2 — Content Engine + Contact Intelligence MCP (Target: Week 2)

Goal: The AI Brain can autonomously operate the content calendar and access contact context.

Deliverables:

• Migrate existing docs/content-engine/mcp-server-spec.md tools into content-engine/src/mcp/
• Contact Intelligence MCP descriptors + internal route handlers (all 7 tools)
• Newsletter MCP descriptors + internal route handlers (all 6 tools)
• Media MCP descriptors (all 5 tools)
• apps/mcp-gateway router updated for all new namespaces
• Tool permission matrix complete in packages/core-access

Done when: An agent can query a contact's memory, check the content calendar, and schedule a post — in one conversation.

Phase 3 — HTTP/SSE Production Transport (Target: With Blog v1.0)

Goal: Customers can connect their AI assistant to their Vlozi workspace via mcp.vlozi.app.

Deliverables:

• apps/mcp-gateway/src/transports/http-sse.ts — Cloudflare Workers SSE transport
• mcp.vlozi.app subdomain configured and routed to apps/mcp-gateway (not apps/gateway)
• CORS + auth for external connections
• Per-plan tool filtering (blog-only plan sees only blog.* tools)
• MCP connection UI in seller dashboard (connect/disconnect, see tool call log)
• Public documentation at docs.vlozi.app/mcp
• Rate limit enforcement for production traffic

Done when: A customer can paste mcp.vlozi.app into Claude Desktop and query their blog.

Phase 4 — Agent Personas & Automation (Post-launch)

Goal: First-party agent personas that customers can enable from the dashboard.

These are pre-built agents that use the MCP tools under the hood:

Each persona is a Claude agent with a system prompt and a restricted set of MCP tools. Customers toggle them on/off per workspace.

12. Local Dev Setup

Prerequisites

• Turbo dev stack running (turbo dev)
• A dev API key with all scopes (generate in seller dashboard or seed script)
• Dev tenant ID

Setup

# 1. Build the mcp-gateway stdio entrypoint
turbo build --filter=mcp-gateway
 
# 2. Set env vars (never commit these)
export VLOZI_DEV_API_KEY=ls_dev_xxxx
export VLOZI_DEV_TENANT_ID=tenant_xxxx
 
# 3. The .mcp.json is already configured — restart Claude Code / Cursor
# Tools will appear in the tool picker immediately

Verifying tools are loaded

In Claude Code, type: what vlozi tools do you have access to? — Claude will list all available tools from the MCP server.

Troubleshooting

13. Key Decisions Log