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/listreturns a per-identity, permission-filtered tool surface.tools/callre-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/mcpcollides with another route in your deployment; client URLs must match.identities— the static on-behalf-of directory (ref → IdentitySubject). See Identities.guardrails.alerts— anyinfrastructure/alertsfactory config (webhook/slack channels reuseurl/webhookUrl, and so on).enabled: falseturns the endpoint off entirely.
How an agent connects
POST /mcpwithAuthorization: Bearer <apiKey>andX-Weavekit-On-Behalf-Of: <ref>, carrying theinitializerequest. The engine creates a session bound to the resolved identity and returns anMcp-Session-Idheader for reuse.tools/listreturns the tool surface compiled for that identity. RBAC decides which operations appear, and each call re-checks the target object.tools/callruns through the RBAC-decorated data-access layer against the session identity. A call-levelonBehalfOfargument 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-resourcereturns{ resource, authorization_servers, bearer_methods_supported, scopes_supported? }(RFC 9728).401responses carryWWW-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/mcpYou 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)
| File | Responsibility |
|---|---|
generate.ts | RBAC capability → generic registry tool surface |
tools.ts | tool execution via data-access + audit + error mapping |
approvals.ts | admin-only list_approvals / approve_approval / reject_approval |
resources.ts | schema-derived, RBAC-filtered resources (weavekit://objects…) |
prompts.ts | schema-derived built-in prompts (RBAC-filtered) + host PromptsProvider |
introspection.ts | list_objects / describe_object |
guardrails.ts | sliding-window rate limit + alert/audit injection |
session.ts | session model + in-memory store (TTL expiry) |
http.ts | fastify /mcp routes; per-session SDK transport + server wiring |
index.ts | registerMcp 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.
Related
- Tool surface
- Custom tools & guardrails
- Audit — the
mcp.tool.*event trail - RBAC — what shapes the tool surface
- Practice: integrate an existing CRM