WeaveKit Docs
GuidesAgents

MCP

Expose objects as agent tools over streamable HTTP, with a per-identity permission-filtered surface.

MCP (Model Context Protocol) is how AI agents operate your data. The engine exposes a streamable HTTP endpoint at /mcp (JSON-RPC 2.0): Claude, Cursor, or any MCP host connects once, then discovers your objects as tools.

Two things make that safe:

  • tools/list returns a per-identity, permission-filtered tool surface.
  • tools/call re-enforces RBAC against the proxied user at call time.

That double layer is the point. Every attempt is also rate-limited, alertable, and audited.

MCP is an adapter — shared by every project type and enabled by default (adapters.mcp undeclared = on).

In this section

  • Tool surface — the fixed registry of tools and how RBAC shapes it
  • Identities — the on-behalf-of directory and plugging in your own user store
  • Guardrails — rate limits, alerts, audit, impersonation
  • Prompts — user-invoked templates: schema-derived built-ins + a provider for business prompts

Enable / configure

// weavekit.config.ts
export default {
  // ...
  adapters: {
    rest: { prefix: '/api' },
    mcp: {
      // endpoint: '/mcp/agent',   // optional: mount on a different path (default /mcp)
      identities: {
        alice: { id: 'u-alice', roles: ['sales'] },
        emma: { id: 'u-emma', roles: ['finance'], departmentId: 'd-east' },
      },
      guardrails: {
        rateLimit: { windowMs: 60_000, max: 100 },   // optional; defaults shown
        alerts: { channel: 'console' },              // console | webhook | slack
      },
    },
  },
};
  • endpoint — path to mount on (default /mcp). Change it if /mcp collides with another route in your deployment; client URLs must match.
  • identities — the static on-behalf-of directory (ref → IdentitySubject). See Identities.
  • guardrails.alerts — any infrastructure/alerts factory config (webhook/slack channels reuse url/webhookUrl, and so on).
  • enabled: false turns the endpoint off entirely.

How an agent connects

  1. POST /mcp with Authorization: Bearer <apiKey> and X-Weavekit-On-Behalf-Of: <ref>, carrying the initialize request. The engine creates a session bound to the resolved identity and returns an Mcp-Session-Id header for reuse.
  2. tools/list returns the tool surface compiled for that identity. RBAC decides which operations appear, and each call re-checks the target object.
  3. tools/call runs through the RBAC-decorated data-access layer against the session identity. A call-level onBehalfOf argument is an optional temporary override.

Auth failures return 401 before the transport is entered. A missing or unknown on-behalf-of ref fails the session with a clear error.

OAuth host discovery (auth.oidc)

When the engine authenticates with a built-in OIDC/JWT verifier (auth.oidc; see Identity), it exposes OAuth 2.0 Protected Resource Metadata so a standards-based MCP host (Claude, ChatGPT connectors, VS Code) can discover the authorization server and run the OAuth flow:

  • GET /.well-known/oauth-protected-resource returns { resource, authorization_servers, bearer_methods_supported, scopes_supported? } (RFC 9728).
  • 401 responses carry WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource", pointing the host at that document.

authorization_servers defaults to [auth.oidc.issuer]; override with auth.oidc.authorizationServers. The document is public (no auth).

Horizontal scaling (session vs stateless)

By default the MCP endpoint is stateful: the initialize handshake creates a server-side session (in process memory) bound to the agent credential + on-behalf-of identity, and later requests carry the Mcp-Session-Id. That requires sticky routing across multiple engine instances.

Set adapters.mcp.stateless: true for stateless Streamable HTTP: each request is self-contained (no server-side session), so the engine scales horizontally without sticky routing. The X-Weavekit-On-Behalf-Of header must accompany every request (there is no session to inherit it).

adapters: { mcp: { stateless: true } },

Enterprise E3 layers multi-instance coordination for timers/quotas/approvals; the base stateless MCP transport stays in the MIT engine.

Wiring

createEngine wires the endpoint for you:

const engine = await createEngine({
  databaseUrl: process.env.DATABASE_URL,
  schemaDir: '.',
  auth: { source: { 'sk-agent': { id: 'agent-1', roles: ['agent'] } } },
  adapters: { mcp: { identities: { alice: { id: 'u-alice', roles: ['sales'] } } } },
});
await engine.app.listen({ port: 3000 });
// MCP endpoint: http://localhost:3000/mcp

You inject the sinks at assembly: audit (a buffered subsystem sink, or a no-op when audit is disabled), alerts (createAlerts), and identity (mcp.identities — a static directory, your own IdentityResolver, or the engine directory by default). The MCP adapter depends only on core contracts; adapters never import subsystems or infrastructure.

The engine is a bridge to your database, not a DDL runner. createEngine loads the schema and never touches your tables. Build or alter tables explicitly with weave migrate — see How migration handles existing tables. (Greenfield and business projects can set migrate.auto: true instead.)

Architecture (src/adapters/mcp)

FileResponsibility
generate.tsRBAC capability → generic registry tool surface
tools.tstool execution via data-access + audit + error mapping
approvals.tsadmin-only list_approvals / approve_approval / reject_approval
resources.tsschema-derived, RBAC-filtered resources (weavekit://objects…)
prompts.tsschema-derived built-in prompts (RBAC-filtered) + host PromptsProvider
introspection.tslist_objects / describe_object
guardrails.tssliding-window rate limit + alert/audit injection
session.tssession model + in-memory store (TTL expiry)
http.tsfastify /mcp routes; per-session SDK transport + server wiring
index.tsregisterMcp assembly (EngineMcpConfig)

The SDK transport is stateful per session: each session owns one StreamableHTTPServerTransport and one SDK Server (the SDK server may connect to only one transport). tools/list and tools/call are served via setRequestHandler, so the surface stays dynamic per identity.

On this page