@oatbox/mcp-server-sdk

Build MCP servers for Oatbox voice agents with visitor-scoped tools.

Install

npm install @oatbox/mcp-server-sdk

Quick start

import { OatboxMCP, visitor_scoped } from "@oatbox/mcp-server-sdk"

const server = new OatboxMCP({
  workspaceId: "acme",
  sharedSecret: process.env.OATBOX_MCP_SECRET!,
})

server.tool("get_subscription_status", visitor_scoped(async ({ visitor }) => {
  return await db.subscriptions.findByUserId(visitor.userId)
}))

server.tool(
  "cancel_subscription",
  visitor_scoped({ requireConfirm: true }, async ({ visitor }) => {
    return await billing.cancel(visitor.userId)
  }),
)

server.start({ port: 3030 })

Why visitor-scoped?

Visitor identity is sealed at session start by Oatbox and cryptographically verifiable on every call. Your MCP server cannot be tricked by prompt injection into impersonating a different visitor — the JWT signed by Oatbox is the source of truth.

See the Oatbox MCP architecture doc for details.

Clock-skew tolerance

JWT iat / exp checks tolerate 30 seconds of clock drift by default — matches typical NTP drift between Oatbox and customer-hosted MCP servers. Override via the clockToleranceSeconds config option:

const server = new OatboxMCP({
  workspaceId: "acme",
  sharedSecret: process.env.OATBOX_MCP_SECRET!,
  clockToleranceSeconds: 5, // strict freshness, e.g. for sensitive write tools
})

Security

This package does not execute any code at install time. Its only runtime dependency is jose — the de-facto Node.js JOSE library, maintained by Auth0 / panva.

Report security issues privately to [email protected] — see the Security Policy. We respond within 24 hours.

Changelog

See CHANGELOG.md.

License

MIT