Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* MCP Streamable HTTP endpoint for `gbrain serve --http` (split out of
* serve-http.ts by refactor wave 1): bearer auth with the resource-audience
* verifier, the per-request effective surface, tools/list and tools/call
* through the shared dispatcher, request logging and the admin SSE feed.
*/
import { createHash } from 'node:crypto';
import type { Express, NextFunction, Request, Response } from 'express';
import { buildDefaultLimiters, type RateLimiter } from '../mcp/rate-limit.ts';
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { DEFAULT_MAX_REQUEST_BODY_SIZE } from '@modelcontextprotocol/sdk/server/requestBody.js';
import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, McpError, ErrorCode, type CallToolRequest } from '@modelcontextprotocol/sdk/types.js';
import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
import { opAllowedForBoundClient } from '../core/operations.ts';
import { authTransport } from '../core/ops/contract.ts';
import type { AuthInfo, Operation } from '../core/operations.ts';
import { disabledOpsForPublishGates } from '../mcp/publish-gates.ts';
import { installInstructionsResolver, MCP_SERVER_DESCRIPTION, readInstructionContent, resolveMcpInstructions } from '../mcp/instructions.ts';
import { httpInstructionTools } from '../mcp/initialize-context.ts';
import { installCapabilitiesResource, mcpAdministrationGuidance } from '../mcp/capabilities.ts';
import { createSkillResources } from '../mcp/skill-resources.ts';
import { resolveAuthCapabilities } from '../core/harness/capabilities.ts';
import { ambientOptsFrom, writebackCaller, type WritebackConfig } from '../core/facts/writeback-config.ts';
import { resolveAgentWriteback } from '../core/facts/writeback-settings.ts';
import { OWNER_MEMBER_KEY } from '../core/search/private-visibility.ts';
import { hasScope, operationScopesAllowed } from '../core/scope.ts';
import { summarizeMcpParams, dispatchToolCall, requestLogStatusForResult, requestMetaSessionId, hotMemoryOffIn, acceptedPendingReceipt, unknownToolEnvelope, errorResult, dispatchRenderContext, grantBlockedNotices, admitNotices, audienceRefusal, type ToolResult } from '../mcp/dispatch.ts';
import { toAgentError } from '../core/agent-output.ts';
import { STATUS_TOOL_NAME, statusModeOf, statusToolResult } from '../mcp/status-mode.ts';
import { isCallable, publishGatesFromDisabled } from '../core/ops/callable.ts';
import { scopeDeniedError } from '../core/ops/op-fix.ts';
import { resolveStrictParamsMode } from '../mcp/validate-params.ts';
import { GBRAIN_CLIENT_HEADER, isGbrainThinClient, resolveResultRowsMode, resultRowsForRequest, type ResultRowsMode } from '../mcp/result-rows.ts';
import { buildToolDefs } from '../mcp/tool-defs.ts';
import { withEngineScope } from '../core/engine-scope.ts';
import {
filterOpsForSurface,
advertisedOps,
clientAdvertisedSurface,
clampSurface,
minSurface,
resolveClientRowSurface,
resolveDefaultClientSurface,
type McpSurface,
} from '../mcp/surface.ts';
import { getBrainHotMemoryMeta } from '../core/facts/meta-hook.ts';
import { ON_BEHALF_OF_HEADER } from '../core/access/audience.ts';
import { ROOM_HEADER } from '../core/access/room.ts';
import { GUEST_HEADER } from '../core/guests/admission.ts';
import { ACTOR_HEADER, EXTERNAL_ID_RE, QM_AUDIENCE_HEADER } from '../core/access/actor-model.ts';
import { parseAgentLabel, AGENT_LABEL_HEADER } from '../core/persistence/attribution.ts';
import { qmMemoryToolResult } from '../core/ops/qm-memory.ts';
import { attestableOp } from '../core/access/actor.ts';
const actorResourceRefusal = () => new McpError(ErrorCode.InvalidRequest,
`actor_not_attested: resources are never read as an attested person, so nothing was read. Read resources without ${ACTOR_HEADER}.`,
{ code: 'actor_not_attested', reason: 'op_not_attested' });
import { serializeError } from '../core/errors.ts';
import { VERSION } from '../version.ts';
import { executeRawJsonb } from '../core/sql-query.ts';
import { withRequestConfigSnapshot } from '../core/config-snapshot.ts';
import { withBearerScopeHint } from './serve-http-oauth.ts';
import { mcpForegroundMiddleware } from '../core/foreground-activity.ts';
import type { ServeHttpContext } from './serve-http.ts';
/** Per-request state shared by the tools/list and tools/call handlers of one POST /mcp. */
interface McpRequestState {
authInfo: AuthInfo;
agentName: string;
startTime: number;
mcpOperations: Operation[];
surface: McpSurface;
surfaceCeiling: McpSurface;
surfaceAllowedOps: ReadonlySet<string> | undefined;
/** C1: search/query row shape for this request (thin-client header, else host `mcp.result_rows`). */
resultRows: ResultRowsMode;
/** Large pages: the same header marks gbrain's thin client, whose default get_page mode stays whole. Never authority. */
thinClient: boolean;
/** GBRA-231: the X-Gbrain-On-Behalf-Of header (a shared agent's audience); bounded by the credential's may_act_for in dispatch. */
onBehalfOfHeader: string | undefined;
/** GBRA-498: the X-Gbrain-Room header (the room an answer goes into); it only marks results, never narrows or widens them. */
roomHeader: string | undefined;
/** GBRA-504: the X-Gbrain-Guest header (guest attribution); read only for a write to a guest source. */
guestHeader: string | undefined;
/** GST-359 C1: the x-qm-actor header (a trusted system names the person); honoured in dispatch only for an attest credential. */
actorHeader: string | undefined;
/** GST-359 D: the x-qm-audience header (QM's channel audience, wave 2); any request carrying it is refused before any work. */
audienceHeader: string | undefined;
/** Wakeshift: the request's User-Agent, which tells it some agent programs apart. Shape only. */
userAgent: string | undefined;
/** The caller's self-declared agent label (X-Gbrain-Agent-Label): recorded on its write requests, never authority. */
agentLabel: string | undefined;
}
export function mountMcp(app: Express, ctx: ServeHttpContext): void {
const { engine, config, resourceVerifier, resourceMetadataUrl, mcpOperationsBase } = ctx;
// ---------------------------------------------------------------------------
// MCP tool calls (bearer auth + scope enforcement)
// ---------------------------------------------------------------------------
// MEMORY_VERBS v1 + WP4 (D2): the server-resolved surface is the CEILING.
// The per-REQUEST effective surface — min(ceiling, client row surface ??
// config default), clamped by the GBRAIN_MCP_FORCE_SURFACE kill switch
// (narrow-only, FOV-6a) — is resolved inside the /mcp handler so a rescope
// or config flip takes effect on the client's next request without a
// restart, and the dispatch allow-set is recomputed per request
// (amendment 20). The surface filter applies AFTER the localOnly filter;
// the same set feeds dispatch as allowedOps so hidden ops are uncallable,
// not just unlisted [c2].
const serverSurfaceCeiling: McpSurface = ctx.surface ?? 'full';
/**
* WP4 (D2): resolve this request's effective surface from the caller's
* verified auth. A legacy bearer token has no client row to pre-seed, so it
* keeps the (clamped) ceiling; its scope, source and operation grants still
* bound it (#9266). The config default (`mcp.default_surface_dcr`) is read
* dual-plane ONLY when an OAuth client row carries no usable surface — the
* common full-surface path pays no extra config read. Unknown row values
* are ignored with a warn-once per client (amendment 18). Never throws:
* surface resolution must not take a request down. On a default-surface
* read failure the LAST successfully read default (per process) still
* applies, so a transient config outage cannot silently widen a client
* that normally resolves narrower than the ceiling; with no prior read,
* the ceiling is the only floor available (pre-WP4 behavior).
*/
let lastKnownDefaultSurface: McpSurface | null = null;
async function resolveEffectiveSurface(authInfo: AuthInfo): Promise<{ ceiling: McpSurface; effective: McpSurface }> {
const ceiling = clampSurface(serverSurfaceCeiling);
// min() can never go below the narrowest surface: a 'verbs' ceiling makes
// the row/default resolution a no-op, so skip the awaited config read.
if (ceiling === 'verbs') return { ceiling, effective: ceiling };
if (authInfo.principal?.kind === 'legacy_token') return { ceiling, effective: ceiling };
const rowSurface = resolveClientRowSurface(authInfo.surface, authInfo.clientId);
if (rowSurface !== null) return { ceiling, effective: minSurface(ceiling, rowSurface) };
try {
const dflt = await resolveDefaultClientSurface(engine, config);
lastKnownDefaultSurface = dflt ?? null;
return { ceiling, effective: minSurface(ceiling, dflt ?? ceiling) };
} catch {
return { ceiling, effective: minSurface(ceiling, lastKnownDefaultSurface ?? ceiling) };
}
}
// v0.36.x #1076: MCP Streamable HTTP spec — GET /mcp opens an optional SSE
// backchannel for server-initiated messages. gbrain's transport is stateless
// and doesn't push server-initiated messages, so per spec we MUST return 405
// (not 404) so probing clients (claude.ai, etc.) recognize this as an MCP
// endpoint, not a missing route. Without this, clients display "endpoint not
// found" instead of "endpoint exists but no SSE channel."
app.get('/mcp', (_req: Request, res: Response) => {
res.set('Allow', 'POST, DELETE');
res.status(405).json({ jsonrpc: '2.0', error: { code: -32000, message: 'Method not allowed' }, id: null });
});
// #5277: hint every scope a connector may need. Clients that request exactly
// the hinted scope and never step up (claude.ai connectors) otherwise stay
// read-only; grantScopes still caps each grant to the client row's scope.
// GBRA-431: the rate limits SECURITY.md documents for /mcp, applied when the operator sets them: the IP bucket before
// the token lookup, the token bucket after it. Unset, serve --http keeps its unlimited default.
const limiters = buildDefaultLimiters();
const ipLimit = rateLimitStep('GBRAIN_HTTP_RATE_LIMIT_IP', limiters.ip, req => req.ip ?? req.socket.remoteAddress ?? 'unknown', 'Too many requests');
const tokenLimit = rateLimitStep('GBRAIN_HTTP_RATE_LIMIT_TOKEN', limiters.token,
req => createHash('sha256').update(((req as any).auth as AuthInfo).token).digest('hex'), 'Too many requests for this token');
app.post('/mcp', ipLimit, withBearerScopeHint(
requireBearerAuth({ verifier: resourceVerifier, resourceMetadataUrl }), ['read', 'write'],
), mcpForegroundMiddleware, tokenLimit, (req: Request, res: Response) => withEngineScope(engine, () => withRequestConfigSnapshot(engine, () => handleMcpPost(req, res))));
// #6721: one config snapshot serves every config read of one POST /mcp (the
// surface, row-shape and writeback reads below, tools/list and a read op's
// dispatch); dispatch reads live for a write op (config-snapshot.ts).
async function handleMcpPost(req: Request, res: Response): Promise<void> {
const startTime = Date.now();
const authInfo = (req as any).auth as AuthInfo;
// Human-readable agent name is now threaded through AuthInfo by
// verifyAccessToken (which JOINs oauth_clients in its existing token
// SELECT). No per-request DB roundtrip needed. Falls back to clientId
// for legacy tokens or when the JOIN row's client_name is NULL.
const agentName = authInfo.clientName ?? authInfo.clientId;
// WP4 (D2): per-request effective surface + fail-closed allow-set,
// recomputed per request (amendment 20) so rescopes/request_tools
// persists take effect on the next request with zero restart.
// Ambient writeback (opt-in, default off) resolves CONCURRENTLY with the
// surface read (performance review, this wave — the two independent DB
// waits must not serialize; an initialize-only resolve is NOT possible
// here because /mcp has no JSON middleware, so req.body is undefined
// until the SDK transport reads the stream — verified by the OAuth
// lifecycle test, which caught exactly that regression). Restart-free
// like the publish gates, fail-closed with a per-engine last-known-good
// bundle so a transient config blip serves the previous bundle instead
// of silently dropping the section mid-session. OV-A5: a token without
// write scope never receives the section (`remember` would be
// uncallable — instructions must not order impossible calls); OV2-14:
// extract_facts is advertised only when this token's ACTUAL visible set
// can call it (surface + scope + bound-client fence — the same
// predicates tools/list applies).
const canWrite = hasScope(authInfo.scopes, 'write');
const [{ ceiling: surfaceCeiling, effective: surface }, writeback, hostResultRows] = await Promise.all([
resolveEffectiveSurface(authInfo),
canWrite ? resolveAgentWriteback(engine, config).then(r => r.bundle) : Promise.resolve(null),
resolveResultRowsMode(engine, config),
]);
// C1: gbrain's thin client keeps full rows. The header is unverified and
// selects a row shape only; it never gates anything security-relevant.
const resultRows = resultRowsForRequest(req.get(GBRAIN_CLIENT_HEADER), hostResultRows);
const mcpOperations = filterOpsForSurface(mcpOperationsBase, surface)
.filter(op => authInfo.allowedOperations == null || authInfo.allowedOperations.includes(op.name));
authInfo.effectiveSurface = surface;
const surfaceAllowedOps: ReadonlySet<string> | undefined =
surface === 'full' && authInfo.allowedOperations == null ? undefined : new Set(mcpOperations.map(o => o.name));
const thinClient = isGbrainThinClient(req.get(GBRAIN_CLIENT_HEADER));
const state: McpRequestState = { authInfo, agentName, startTime, mcpOperations, surface, surfaceCeiling, surfaceAllowedOps, resultRows, thinClient,
onBehalfOfHeader: req.get(ON_BEHALF_OF_HEADER), roomHeader: req.get(ROOM_HEADER), guestHeader: req.get(GUEST_HEADER), actorHeader: req.get(ACTOR_HEADER), audienceHeader: req.get(QM_AUDIENCE_HEADER),
userAgent: req.get('user-agent'), agentLabel: parseAgentLabel(req.get(AGENT_LABEL_HEADER)) };
const server = createMcpRequestServer(ctx, state, writeback, writeback?.enabled ? await engine.getConfig(OWNER_MEMBER_KEY).catch(() => null) : null);
await serveMcpRequest(server, req, res);
}
}
function createMcpRequestServer(
ctx: ServeHttpContext,
state: McpRequestState,
writeback: WritebackConfig | null,
ownerMember: string | null,
): Server {
const { engine, config, mcpResourceUrl } = ctx;
const { authInfo, mcpOperations, surface, surfaceCeiling, surfaceAllowedOps } = state;
// Create a fresh MCP server per request (stateless).
let writebackOpts: ReturnType<typeof ambientOptsFrom> = null;
if (writeback) {
// Both availability probes apply the SAME predicates tools/list does
// (surface filter + bound-client fence): a slug-bound client whose
// fence denies `remember` receives NO ambient section at all —
// instructions must never order calls dispatch will deny.
const rememberOp = mcpOperations.find(o => o.name === 'remember');
const extractFactsOp = mcpOperations.find(o => o.name === 'extract_facts');
writebackOpts = ambientOptsFrom(writeback, {
remember: rememberOp !== undefined && opAllowedForBoundClient(authInfo, rememberOp),
extractFacts: extractFactsOp !== undefined && opAllowedForBoundClient(authInfo, extractFactsOp),
...writebackCaller(authInfo, ownerMember),
});
}
const server = new Server(
{ name: 'gbrain', version: VERSION, description: MCP_SERVER_DESCRIPTION },
{
capabilities: { tools: {}, resources: {} },
// #4748: contract (+ opt-in writeback section) + deployment identity.
instructions: resolveMcpInstructions(config, process.env, { writeback: writebackOpts }),
},
);
// F1: the contract for THIS token's callable set + readiness tail, resolved at initialize.
installInstructionsResolver(server, async () => resolveMcpInstructions(config, process.env, {
writeback: writebackOpts,
tools: await httpInstructionTools(engine, config, { ops: mcpOperations, surface, auth: authInfo, allowedOps: surfaceAllowedOps, cache: ctx.readinessCache, advertise: ctx.advertise ?? null }),
...await readInstructionContent(engine),
}));
installCapabilitiesResource(server, async () => {
return { transport: authTransport(authInfo), client_id: authInfo.clientId,
...await resolveAuthCapabilities(authInfo, engine, config), administration: mcpAdministrationGuidance(mcpResourceUrl.toString()) };
}, state.actorHeader != null || state.audienceHeader !== undefined ? undefined : createSkillResources(engine, async () => {
const sourceId = authInfo.sourceId ?? 'default';
const { noGrantFederatedScope } = await import('../core/source-resolver.ts');
return { remote: true, transport: 'http', sourceId, auth: authInfo, config,
localFederatedSourceIds: await noGrantFederatedScope(engine, authInfo.hasSourceGrant, sourceId),
allowedOps: surfaceAllowedOps, surface, surfaceCeiling };
}));
// GST-359 C1: resources are never read as an attested person, so a request naming one reads none.
if (state.actorHeader != null) server.setRequestHandler(ReadResourceRequestSchema, async () => { throw actorResourceRefusal(); });
// GST-359 D: a request carrying x-qm-audience is refused before any work, on every method that reads or runs a tool.
if (state.audienceHeader !== undefined) {
const refusal = (op: string) => audienceRefusal(op, { auth: authInfo, transport: 'http' });
const rpcRefusal = (method: string) => { const { rpc } = refusal(method); return new McpError(ErrorCode.InvalidRequest, rpc.message, rpc.data); };
for (const [schema, method] of [[ListResourcesRequestSchema, 'resources/list'], [ReadResourceRequestSchema, 'resources/read'], [ListToolsRequestSchema, 'tools/list']] as const) {
server.setRequestHandler(schema, async () => { throw rpcRefusal(method); });
}
server.setRequestHandler(CallToolRequestSchema, async (request) => refusal(request.params.name).result);
return server;
}
server.setRequestHandler(ListToolsRequestSchema, async () => listMcpTools(ctx, state));
server.setRequestHandler(CallToolRequestSchema, async (request) => callMcpTool(ctx, state, request));
return server;
}
async function listMcpTools(ctx: ServeHttpContext, state: McpRequestState) {
const { engine, config, broadcastEvent } = ctx;
const { authInfo, agentName, startTime, mcpOperations, surface, surfaceAllowedOps } = state;
// WP1 honest catalog: the advertised list is exactly what THIS token
// can call. Three per-request filters, cheapest first:
// 1. token scope — a read-only token never sees admin/write tools;
// 2. bound-client fence — a slug-bound client never sees ops the
// dispatch fence would deny (same predicate, cannot drift);
// 3. publish gates — gated ops (skills/advisor) are hidden while
// their gate is off; the resolver never throws (read failure =
// hidden, matching the default-off consent posture) so a config
// hiccup costs at most the 4 gated tools, never the whole list.
// Call-time enforcement (hasScope / fence / assertPublishEnabled)
// stays as the fail-closed backstop for all three layers.
// Both per-request config reads are independent — issue them
// concurrently (one RTT of latency on network Postgres, not two).
const [gateDisabled, strictParamsMode, advertised] = await Promise.all([
disabledOpsForPublishGates(engine, config),
resolveStrictParamsMode(engine, config),
clientAdvertisedSurface(authInfo, engine, config, ctx.advertise ?? null),
]);
// FOV-4: `agent` deliberately implies only itself, which would strand
// agent-only tokens with ZERO discovery — ops flagged `agentCallable`
// (request_tools) are visible to (and callable by, below) agent scope
// in addition to their declared scope.
// Agent contract v1 (A2): the one callability predicate (isCallable) plus
// the bound-client op fence.
const publishGates = publishGatesFromDisabled(mcpOperations, gateDisabled);
// GST-359 C1: under a valid x-qm-actor header from an attest credential, only the operations it may run as the person.
const attest = state.actorHeader != null && EXTERNAL_ID_RE.test(state.actorHeader) ? authInfo.attest : null;
const visibleOps = mcpOperations.filter(op =>
isCallable(op, { transport: 'http', surface, scopes: authInfo.scopes, publishGates, allowedOps: surfaceAllowedOps })
&& opAllowedForBoundClient(authInfo, op) && (!attest || (attest.ops.includes(op.name) && attestableOp(op.name, op))),
);
// WP3 (amendment 14): ONE schema mapper — the inline map this handler
// carried is unified onto buildToolDefs so the byte-pin test covers the
// transport consumers actually use. strict_params is read dual-plane
// PER REQUEST (same restart-free property as the publish gates above):
// 'reject' closes each schema with additionalProperties:false and
// declares the _meta/dry_run passthrough keys (D14.1).
const strictParams = strictParamsMode === 'reject';
// mcp.advertised_surface narrows the list only; dispatch below keeps the callable set (request_tools reaches the rest).
// A client that chose its own surface (request_tools {surface}, an operator rescope) gets that surface listed in full.
const tools = buildToolDefs(advertisedOps(visibleOps, surface, advertised), { strictParams });
// v0.28.10: log every JSON-RPC method, not just successful tools/call.
// Pre-fix, /admin/api/requests showed nothing for clients that only
// ever called tools/list, and the v0.26.3 persistence regression test
// asserting >= 2 rows after tools/list + tools/call was unreachable.
// Amendment 23 stopgap (full list-size telemetry deferred): the row's
// params carry the listed-tool count so per-token-class list sizes are
// queryable (`params->>'tool_count'`) without new telemetry plumbing.
const latency = Date.now() - startTime;
try {
await executeRawJsonb(
engine,
`INSERT INTO mcp_request_log (token_name, agent_name, operation, latency_ms, status, params)
VALUES ($1, $2, $3, $4, $5, $6::jsonb)`,
[authInfo.clientId, agentName, 'tools/list', latency, 'success'],
[{ tool_count: tools.length }],
);
} catch { /* best effort */ }
broadcastEvent({
agent: agentName,
operation: 'tools/list',
scopes: authInfo.scopes.join(','),
latency_ms: latency,
status: 'success',
timestamp: new Date().toISOString(),
});
return { tools };
}
async function callMcpTool(ctx: ServeHttpContext, state: McpRequestState, request: CallToolRequest): Promise<ToolResult> {
const { engine, broadcastEvent, logFullParams } = ctx;
const { authInfo, agentName, startTime, mcpOperations, surface, surfaceCeiling, surfaceAllowedOps, resultRows, thinClient } = state;
const { name, arguments: params } = request.params;
// A server that recovered from status-only mode answers clients still holding the status tool list (never listed).
const statusMode = name === STATUS_TOOL_NAME ? statusModeOf(engine) : null;
if (statusMode && hasScope(authInfo.scopes, 'read')) return statusToolResult(statusMode, 'http');
const op = mcpOperations.find(o => o.name === name);
if (!op) {
return qmMemoryToolResult(name, await rejectUnknownMcpOperation(ctx, state, name, requestMetaSessionId(request.params)), state.actorHeader != null);
}
// Scope enforcement (v0.28: hasScope replaces exact-string-match so
// admin tokens satisfy any scope, write satisfies read, and the new
// sources_admin / users_admin scopes resolve through the same
// hierarchy. Plain string includes() at this site would have made
// sources_admin tokens look like they couldn't even read.)
const requiredScope = op.scope || 'read';
// FOV-4: agentCallable carve-out mirrors the tools/list filter above —
// an op listed for an agent-only token must not scope-deny at call time.
// #5575: an owner-only (cliOnly) op is refused for every remote caller by the
// shared dispatcher with `trusted_local_only` and the host command; a scope
// denial first would tell the operator to widen the grant for nothing.
const scopeSatisfied = op.cliOnly !== undefined || operationScopesAllowed(authInfo.scopes, op);
if (!scopeSatisfied) {
return qmMemoryToolResult(name, await rejectInsufficientMcpScope(ctx, state, name, requiredScope, requestMetaSessionId(request.params)), state.actorHeader != null);
}
// F8: redact request payload by default (declared keys only via the
// op's `params` allow-list; values + attacker-controlled key names
// never written to mcp_request_log or the SSE feed). --log-full-params
// bypasses this for operators debugging on their own laptop, with the
// startup warning printed earlier.
//
// D1 (v0.31 wave): mcp_request_log.params is JSONB. Pre-v0.31 wrote
// a JSON-string into that JSONB column via the postgres.js template
// tag's loose typing — readable but semantically wrong (params->>'op'
// would return the encoded string, not the value). Post-v0.31 we
// pass the OBJECT through executeRawJsonb with an explicit ::jsonb
// cast, so reads return real objects and `params->>'op'` returns
// 'tools/list'. Pre-existing string-shaped rows are normalized by
// migration v41 in src/core/migrate.ts.
const safeParamsSummary = summarizeMcpParams(name, params);
// Wakeshift's session_key is a conversation credential: never logged, even under --log-full-params.
const fullParams = params && typeof params === 'object' && 'session_key' in params ? { ...params, session_key: '[redacted]' } : params;
const logParamsObj: unknown = logFullParams
? (fullParams || null)
: (safeParamsSummary || null);
const broadcastParams = logFullParams ? (fullParams || {}) : safeParamsSummary;
// v0.31 (D12 / eE1): refactor the inlined op.handler call to go through
// src/mcp/dispatch.ts so HTTP MCP shares the same dispatch path as
// stdio MCP. The dispatcher does param validation, OperationContext
// build, error envelope unification, and (new) `_meta.brain_hot_memory`
// injection via the metaHook. HTTP-specific concerns (mcp_request_log
// persistence + SSE broadcast) stay here; the dispatcher returns the
// ToolResult and we read isError + _meta to pick the right branch.
// #2529: takesHoldersAllowList is a typed AuthInfo field populated by
// verifyAccessToken from access_tokens.permissions.takes_holders for
// legacy bearer tokens ([] preserved as deny-all). The fail-closed
// ['world'] default covers OAuth-client tokens (no per-client storage
// yet — see TODOS.md) and pre-v29 brains (no permissions column →
// isUndefinedColumnError fallback in verifyAccessToken).
const tokenAllowList = authInfo.takesHoldersAllowList ?? ['world'];
// v0.34.1 (#861, D13): AuthInfo.sourceId is now a real typed field
// populated from oauth_clients.source_id (migration v60 backfilled
// NULL → 'default'). Pre-fix this site cast through AuthInfo and
// fell back to GBRAIN_SOURCE env / 'default' — the silent-fallback
// path codex flagged in plan review. Post-v60, every OAuth client
// has source_id set; legacy bearer tokens default to 'default' in
// verifyAccessToken. The env-fallback is gone.
const tokenSourceId = authInfo.sourceId ?? 'default';
// #3242 parity: the legacy-transport and stdio dispatch sites widen a
// no-grant caller's unqualified reads across the federated source set
// (localFederatedSourceIds); this SDK-transport site never did, so the
// same token saw federated pages over /mcp on one serve mode and scalar
// 'default' on the other. hasSourceGrant === false is set ONLY for
// legacy bearer tokens with no operator source grant (oauth-provider);
// granted tokens and OAuth clients never widen. Best-effort: a resolver
// failure keeps the scalar scope.
const { noGrantFederatedScope } = await import('../core/source-resolver.ts');
const localFederated = await noGrantFederatedScope(
engine,
authInfo.hasSourceGrant,
tokenSourceId,
);
// #4817: written before dispatch, so a request that never returns (a spin
// the stall watchdog later kills) still leaves its op name and an argument
// digest behind. The digest identifies the request without logging content.
let argsDigest = 'none';
try { argsDigest = createHash('sha256').update(JSON.stringify(params ?? null)).digest('hex').slice(0, 16); } catch { /* unserializable */ }
process.stderr.write(`[gbrain-serve] dispatch op=${name} args_sha256=${argsDigest}\n`);
// CX2-11 parity with stdio: the request-level `_meta.session_id` (a sibling
// of `arguments`) becomes OperationContext.sessionId, so the hot-memory
// metaHook and every other session consumer key per remote session. Identity
// only, never a trust surface.
const sessionId = requestMetaSessionId(request.params);
let toolResult: Awaited<ReturnType<typeof dispatchToolCall>>;
try {
toolResult = await dispatchToolCall(engine, name, params as Record<string, unknown> | undefined, {
remote: true,
admissionOrigin: 'interactive',
config: ctx.config,
// WP1/D7: network transport — the dispatch-layer localOnly
// backstop keys off this marker.
transport: 'http',
inboundFrameBytes: mcpBodyCap(),
...(sessionId ? { sessionId } : {}),
...(hotMemoryOffIn(request.params) ? { hotMemoryOff: true } : {}),
onBehalfOf: { header: state.onBehalfOfHeader, requestMeta: (request.params as { _meta?: unknown })._meta },
room: { header: state.roomHeader, requestMeta: (request.params as { _meta?: unknown })._meta },
guest: { header: state.guestHeader, requestMeta: (request.params as { _meta?: unknown })._meta },
mcpCaller: { client: authInfo.clientName, userAgent: state.userAgent, meta: (request.params as { _meta?: Record<string, unknown> })._meta },
actor: { header: state.actorHeader, audience: state.audienceHeader },
...(state.agentLabel ? { agentLabel: state.agentLabel } : {}),
takesHoldersAllowList: tokenAllowList,
sourceId: tokenSourceId,
...(localFederated ? { localFederatedSourceIds: localFederated } : {}),
metaHook: getBrainHotMemoryMeta,
...(ctx.noticeLedger ? { noticeLedger: ctx.noticeLedger } : {}),
// MEMORY_VERBS v1: fail-closed surface enforcement + usage attribution.
...(surfaceAllowedOps ? { allowedOps: surfaceAllowedOps } : {}),
surface,
// WP4 (D2): request_tools bounds its catalog + persist by this.
surfaceCeiling,
// D2: a callable tool the advertised surface leaves out of tools/list (same rule as listMcpTools).
isListed: async op => advertisedOps([op], surface, await clientAdvertisedSurface(authInfo, engine, ctx.config, ctx.advertise ?? null)).length > 0,
resultRows,
...(thinClient ? { thinClient: true } : {}),
// v0.31 follow-up fix: thread auth so the whoami op (and any
// future scope-aware handlers) can introspect the caller. The
// original D12/eE1 refactor moved dispatch into dispatchToolCall
// but forgot to pass authInfo; whoami fell through to the
// unknown_transport throw because ctx.auth was undefined.
auth: authInfo,
logger: {
info: (msg: string) => console.error(`[INFO] ${msg}`),
warn: (msg: string) => console.error(`[WARN] ${msg}`),
error: (msg: string) => console.error(`[ERROR] ${msg}`),
},
});
} catch (e) {
// dispatchToolCall absorbs OperationError + Error and returns
// isError:true; only an unexpected throw lands here. Treat as the
// F15 unified envelope. v0.31 wave (D1): mcp_request_log.params is
// JSONB — write the object via executeRawJsonb so reads return a
// real object, not a JSON-encoded string.
const latency = Date.now() - startTime;
const errorPayload = serializeError(e);
try {
await executeRawJsonb(
engine,
`INSERT INTO mcp_request_log (token_name, agent_name, operation, latency_ms, status, error_message, params)
VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb)`,
[authInfo.clientId, agentName, name, latency, 'error', errorPayload.message],
[logParamsObj],
);
} catch { /* best effort */ }
broadcastEvent({
agent: agentName,
operation: name,
params: broadcastParams,
scopes: authInfo.scopes.join(','),
latency_ms: latency,
status: 'error',
error: errorPayload,
timestamp: new Date().toISOString(),
});
// Agent contract v1 (A1): the one envelope, not the nested legacy StructuredError.
return errorResult(e, { remote: true, transport: 'http', auth: authInfo, surface, ...(surfaceAllowedOps ? { allowedOps: surfaceAllowedOps } : {}) }, { op: name });
}
return recordMcpToolResult(ctx, state, name, toolResult, logParamsObj, broadcastParams);
}
async function rejectUnknownMcpOperation(ctx: ServeHttpContext, state: McpRequestState, name: string, sessionId?: string): Promise<ToolResult> {
const { engine, broadcastEvent } = ctx;
const { authInfo, agentName, startTime } = state;
// v0.28.10: persist unknown-op attempts. Operators investigating
// misbehaving agents need to see the full attempt log, not just
// valid-op success/error.
const latency = Date.now() - startTime;
try {
await executeRawJsonb(
engine,
`INSERT INTO mcp_request_log (token_name, agent_name, operation, latency_ms, status, error_message, params)
VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb)`,
[authInfo.clientId, agentName, name, latency, 'error', `unknown_operation: ${name}`],
[null],
);
} catch { /* best effort */ }
broadcastEvent({
agent: agentName,
operation: name,
scopes: authInfo.scopes.join(','),
latency_ms: latency,
status: 'error',
error: { code: 'unknown_operation', message: `Unknown: ${name}` },
timestamp: new Date().toISOString(),
});
// Frozen v1 pair: `error: unknown_operation` stays; `code: unknown_tool`.
const opts = { remote: true, transport: 'http' as const, auth: authInfo, surface: state.surface, config: ctx.config, surfaceCeiling: state.surfaceCeiling,
...(sessionId ? { sessionId } : {}), ...(ctx.noticeLedger ? { noticeLedger: ctx.noticeLedger } : {}),
...(state.surfaceAllowedOps ? { allowedOps: state.surfaceAllowedOps } : {}) };
return unknownToolEnvelope(name, opts, 'unknown_operation', await grantBlockedNotices(engine, opts, true));
}
async function rejectInsufficientMcpScope(
ctx: ServeHttpContext,
state: McpRequestState,
name: string,
requiredScope: string,
sessionId?: string,
): Promise<ToolResult> {
const { engine, broadcastEvent } = ctx;
const { authInfo, agentName, startTime } = state;
// v0.28.10: persist scope-rejected attempts. Same operator-visibility
// motivation as the unknown-op path — and it makes the v0.26.3
// persistence regression test reliable across both rejection paths.
// Amendment 33: a call-time scope deny is a LIST-LEVEL denial (the
// tools/list filter uses this same hasScope predicate, so the op was
// never advertised to this token — the client ignored or staled its
// list, or list/call drifted). status='denied_after_list' makes the
// honest-catalog metric a one-line count that trends to zero.
const latency = Date.now() - startTime;
try {
await executeRawJsonb(
engine,
`INSERT INTO mcp_request_log (token_name, agent_name, operation, latency_ms, status, error_message, params)
VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb)`,
[authInfo.clientId, agentName, name, latency, 'denied_after_list', `insufficient_scope: requires '${requiredScope}'`],
[null],
);
} catch { /* best effort */ }
broadcastEvent({
agent: agentName,
operation: name,
scopes: authInfo.scopes.join(','),
latency_ms: latency,
status: 'denied_after_list',
error: { code: 'insufficient_scope', message: `requires '${requiredScope}'` },
timestamp: new Date().toISOString(),
});
const denial = scopeDeniedError({ op: name, required: [requiredScope], auth: authInfo, transport: 'http' });
const opts = { remote: true, transport: 'http' as const, auth: authInfo, config: ctx.config, surfaceCeiling: state.surfaceCeiling,
...(sessionId ? { sessionId } : {}), ...(ctx.noticeLedger ? { noticeLedger: ctx.noticeLedger } : {}) };
const notices = await grantBlockedNotices(engine, opts, true);
if (notices.length) denial.notices = admitNotices(notices, opts);
const envelope = toAgentError(denial, { transport: 'http', op: name, render: dispatchRenderContext(opts) });
return { content: [{ type: 'text', text: JSON.stringify({ ...envelope, your_scopes: authInfo.scopes }) }], isError: true };
}
async function recordMcpToolResult(
ctx: ServeHttpContext,
state: McpRequestState,
name: string,
toolResult: ToolResult,
logParamsObj: unknown,
broadcastParams: unknown,
): Promise<ToolResult> {
const { engine, broadcastEvent } = ctx;
const { authInfo, agentName, startTime } = state;
const latency = Date.now() - startTime;
if (toolResult.isError) {
// dispatchToolCall serializes the error into the content text;
// for the audit log we re-extract a message string for the
// mcp_request_log error_message column. Best-effort parse.
// Amendment 33 / D10: op-level denials the list should have
// prevented (publish-gate backstop `config_key=...`, bound-client
// fence op-level deny `fence=op`) log status='denied_after_list'
// instead of plain 'error' — the honest-catalog trend-to-zero
// metric. Argument-level fence denials carry no marker and stay
// 'error' (legitimate for a listed op).
let errMsg = 'unknown_error';
try {
const parsed = JSON.parse(toolResult.content[0]?.text ?? '{}');
errMsg = parsed.error?.message ?? parsed.message ?? errMsg;
} catch { /* ignore */ }
const errStatus = requestLogStatusForResult(toolResult);
// #5249: the opaque request id lets admin stats count pending writes that later fail.
const pending = errStatus === 'accepted_pending' ? acceptedPendingReceipt(toolResult) : null;
try {
await executeRawJsonb(
engine,
`INSERT INTO mcp_request_log (token_name, agent_name, operation, latency_ms, status, error_message, params)
VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb)`,
[authInfo.clientId, agentName, name, latency, errStatus, errMsg],
[pending ? { ...(logParamsObj && typeof logParamsObj === 'object' ? logParamsObj : {}), write_request_id: pending.request_id } : logParamsObj],
);
} catch { /* best effort */ }
broadcastEvent({
agent: agentName,
operation: name,
params: broadcastParams,
scopes: authInfo.scopes.join(','),
latency_ms: latency,
status: errStatus,
error: { code: 'op_error', message: errMsg },
timestamp: new Date().toISOString(),
});
return toolResult;
}
// WP3 (amendment 13): warn-mode observability. A success whose _meta
// carries a non-empty warnings array logs as 'success_with_warnings' so
// the reject-flip decision is evidence-based (count per client via the
// status column). Warn CONTENTS (the raw unknown keys) are never logged.
const successStatus = requestLogStatusForResult(toolResult);
try {
await executeRawJsonb(
engine,
`INSERT INTO mcp_request_log (token_name, agent_name, operation, latency_ms, status, params)
VALUES ($1, $2, $3, $4, $5, $6::jsonb)`,
[authInfo.clientId, agentName, name, latency, successStatus],
[successStatus === 'accepted_pending' ? { ...(logParamsObj && typeof logParamsObj === 'object' ? logParamsObj : {}), write_request_id: acceptedPendingReceipt(toolResult)?.request_id } : logParamsObj],
);
} catch { /* best effort */ }
broadcastEvent({
agent: agentName,
operation: name,
params: broadcastParams,
scopes: authInfo.scopes.join(','),
latency_ms: latency,
status: successStatus,
timestamp: new Date().toISOString(),
});
return toolResult;
}
/** A positive integer env var, or undefined when unset or not one. */
function positiveEnvInt(name: string): number | undefined {
const raw = process.env[name]?.trim();
if (!raw) return undefined;
const n = /^\d+$/.test(raw) ? Number(raw) : NaN;
if (Number.isSafeInteger(n) && n > 0) return n;
console.error(`[serve-http] ${name}=${JSON.stringify(raw)} is not a positive whole number; ignoring it.`);
return undefined;
}
/** GBRA-431: the POST /mcp body cap, GBRAIN_HTTP_MAX_BODY_BYTES when the operator sets it, else the SDK's 4 MiB. Over it the SDK answers 413 before the body is read. */
function mcpBodyCap(): number {
return positiveEnvInt('GBRAIN_HTTP_MAX_BODY_BYTES') ?? DEFAULT_MAX_REQUEST_BODY_SIZE;
}
/** One rate-limit bucket as an Express step: a no-op while `envName` is unset, else 429 with Retry-After once the key's bucket is empty. */
function rateLimitStep(envName: string, limiter: RateLimiter, key: (req: Request) => string, message: string) {
const enabled = positiveEnvInt(envName) !== undefined;
return (req: Request, res: Response, next: NextFunction) => {
if (!enabled) return next();
const check = limiter.check(key(req));
if (check.allowed) return next();
res.set('Retry-After', String(check.retryAfter ?? 60)).status(429).json({ error: 'rate_limited', message });
};
}
async function serveMcpRequest(server: Server, req: Request, res: Response): Promise<void> {
// F14: wrap transport setup + handleRequest in try/catch. Without this,
// an SDK-level throw (e.g., schema parse failure on a malformed request)
// propagates to express's default error handler, which renders an HTML
// error page — clients expecting JSON-RPC envelopes break. On
// !res.headersSent we emit a minimal JSON 500 so the client at least
// gets parseable JSON back.
try {
const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined as any, maxRequestBodySize: mcpBodyCap() });
// #2844: per-request teardown (SDK stateless pattern) — without it every POST /mcp leaks the transport+Server pair (~3GB/day RSS). Registered BEFORE connect/handleRequest so early disconnects and handleRequest throws still clean up; best-effort catches so cleanup never surfaces an unhandledRejection.
res.on('close', () => { transport.close().catch(() => {}); server.close().catch(() => {}); });
await server.connect(transport);
await transport.handleRequest(req, res, req.body);
} catch (e) {
console.error('MCP request handler error:', e instanceof Error ? e.message : e);
if (!res.headersSent) {
res.status(500).json(toAgentError(e, { transport: 'http', render: dispatchRenderContext({ remote: true, transport: 'http' }) }));
}
}
}