MCP server

@hogsend/mcp is a Model Context Protocol server for Hogsend. It gives an MCP client an agent-facing surface over your instance's admin API — author and operate Journey Blueprints, pull a health report, and send a test email — without a deploy in the loop.

It ships two transports over one tool implementation:

• stdio — npx @hogsend/mcp, for a local client (Claude Desktop, Cursor, any stdio MCP client).
• Streamable HTTP — a consumer-mounted route at POST /v1/mcp, for claude.ai connectors and any remote Streamable-HTTP client.

Both build the same server, and both talk to the admin API with a full-admin key — the stdio bin over real fetch, the hosted route in-process through the same requireAdmin gate as the rest of the admin surface.

The surface

Local clients (stdio)

The server runs over stdio via npx — nothing to install. Point it at your instance with two env vars.

Claude Desktop

Add the server to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "hogsend": {
      "command": "npx",
      "args": ["-y", "@hogsend/mcp"],
      "env": {
        "HOGSEND_API_URL": "https://api.your-instance.com",
        "HOGSEND_ADMIN_KEY": "hsk_your_admin_key"
      }
    }
  }
}

Cursor

Cursor uses the same mcpServers shape in ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "hogsend": {
      "command": "npx",
      "args": ["-y", "@hogsend/mcp"],
      "env": {
        "HOGSEND_API_URL": "https://api.your-instance.com",
        "HOGSEND_ADMIN_KEY": "hsk_your_admin_key"
      }
    }
  }
}

Configuration

• The key rides the Authorization: Bearer header only — it is never placed in a URL or query string.
• A flag overrides its env var per run. With no key configured the bin exits with a clear error rather than starting.

Hosted transport (claude.ai connectors)

For a remote client like a claude.ai custom connector, the consumer app mounts the hosted transport. @hogsend/mcp exports mcpRoutes() for createApp's existing routes option — the same pattern the cold-connect and Telegram routes use:

// src/index.ts
import { createApp, createHogsendClient } from "@hogsend/engine";
import { mcpRoutes } from "@hogsend/mcp";

const client = createHogsendClient({ journeys, email: { templates } });

const app = createApp(client, {
  routes: [mcpRoutes()],
  webhookSources,
});

That serves the MCP server over Streamable HTTP at:

POST /v1/mcp

The route is stateless (a fresh server per request) and admin-gated by the same requireAdmin that guards every other admin route. There is no new env flag and no OAuth build — mounting the route is the opt-in. Only POST is served — a GET or DELETE to /v1/mcp returns 405 Method Not Allowed (the server is stateless, so there is no SSE stream to open or session to terminate).

Bundling requirements

@hogsend/mcp ships its library surface as raw src/*.ts (like the other @hogsend/* packages), so a consumer that bundles with tsup must do two things or the app boot-crashes on an unresolvable import at runtime:

1. Bundle @hogsend/mcp. Add it to your tsup.config.ts noExternal array so its .js-suffixed relative imports resolve against the .ts sources at build time:

   // tsup.config.ts
   noExternal: ["@hogsend/engine", "@hogsend/mcp" /* …other @hogsend/* deps */],

2. Install its runtime deps as your own. @hono/mcp and @modelcontextprotocol/sdk stay external when @hogsend/mcp is bundled, so they must resolve from your node_modules. Declare them as direct dependencies:

   pnpm add @hono/mcp @modelcontextprotocol/sdk

Connecting from claude.ai

Add a custom connector pointing at your instance, and authenticate with a static header (currently a beta connector-auth method on claude.ai):

1. Deploy an instance that mounts mcpRoutes() (above) and mint a full-admin admin key.
2. In claude.ai, add a custom connector with the URL https://api.your-instance.com/v1/mcp.
3. Set a static header Authorization: Bearer hsk_your_admin_key. This is the one place the key is pasted; it rides the header on every request.

ChatGPT connectors

Not supported in v1. ChatGPT's connector framework requires OAuth, which @hogsend/mcp does not implement — the hosted route authenticates with the admin key via requireAdmin, not an OAuth flow.

What the report checks

hogsend_report runs pure, unit-tested heuristics over existing admin metrics routes. Pick a scope:

Every report envelope also carries the calling credential's identity (GET /v1/admin/api-keys/self), so the output says whose key produced it. Thresholds are conservative, and findings are ranked critical → warning → info.

Security notes

• The key is a production secret. It is full-admin-scoped — it can author, enable, and disable automations and send real email. Store it the way you store any admin credential.
• Never put the key in a URL or query parameter. Both transports carry it in the Authorization header only; the MCP spec bans query-param credentials because they leak into logs.
• The hosted route grants no extra privilege. It runs in-process with the inbound credential and re-checks requireAdmin on every call — a caller is only ever as authorized as their own key.
• send_test_email reaches a real inbox. It renders the template and dispatches a message with preference checks skipped. Use manage_blueprint action=validate or a template preview for non-delivering checks.

Related

• hogsend blueprints — list Journey Blueprints and promote them to code-first defineJourney() files.
• Hogsend for AI agents — the vendored Claude Code skills, the hogsend CLI, and /llms.txt.
• Vercel AI SDK — run an agent inside a journey (the complement to operating Hogsend from an agent).