Mount the Model Context Protocol on any Express app so AI clients (Cursor, Claude, Gemini Spark Connected Apps, and other MCP-compatible tools) can agentically interact with your pre-existing API server without standing up a separate MCP server.
Register tools against your existing business logic, optionally add OAuth SSO (GitHub/Google), a FlexSearch knowledge base, and an in-process LLM agent. This package ships ; your host Express app remains in control of TLS, CORS, body parsers, and rate limits.
Add MCP tools, OAuth, and a knowledge base to any Express app so AI clients can call your APIs
2026-11-10
Sterne
—
Tools
—
Uptime
—
routers and middleware only
Features
Drop-in MCP on Express — Mount JSON-RPC MCP endpoints on the app you already run
Your tools, your data — Register custom tools that wrap existing APIs and services
Optional OAuth SSO — GitHub/Google login, Bearer JWTs, PKCE, and Dynamic Client Registration for MCP clients
Gemini Spark Connected Apps — First-class Google Account Linking for Spark: default DCR allowlist for oauth-redirect*.googleusercontent.com, wire-encoded state echo, and refresh_token issuance
Built-in knowledge base — Full-text document search via FlexSearch (kb_search, kb_list, kb_get) plus MCP resources at kb://{name|documents}/{id}
MCP resources — Expose playbooks/SOPs via resources/list and resources/read (BaseResource / registerResource)
Tool name prefixing — Avoid collisions when multiple MCP services share a client
Optional agent — Gemini-backed agent_ask that can call your registered tools
Optional telemetry — OpenInference / GenAI OTLP spans for tool calls and agent turns (http/json, http/protobuf, or grpc; see docs/TELEMETRY.md)
Pluggable hooks — In-process BaseHook middleware for SessionStart, PreToolUse, PermissionRequest, PostToolUse, UserPromptSubmit, and Stop
Requirements
Node.js: Version 20 or higher
Express: Version ^4.18.0 || ^5.0.0 (peer dependency)
Installation
npm install @brandon-svec/express_mcp express
Express is a peer dependency. Ensure you have Express ^4.18.0 or ^5.0.0 installed in your project.
Quick Start
import express from 'express';
import { ExpressMcp, BaseTool, BaseResource } from '@brandon-svec/express_mcp';
const app = express();
app.use(express.json());
const expressMcp = new ExpressMcp();
// Extend BaseTool: name + description for tools/list, inputSchema for args, execute for the handler
class GreetingTool extends BaseTool {
constructor() {
super('greeting', 'A simple greeting tool'); // Tool name and description for your agent to know when to use the tool
this.inputSchema = {
type: 'object',
properties: {
name: { type: 'string', description: 'Name to greet' } // Good descriptions improve agent operations
},
required: ['name']
};
}
async execute(params) {
return `Hello, ${params.name}!`;
}
}
expressMcp.registerTool(new GreetingTool());
app.use('/mcp', expressMcp.router());
app.listen(3000, () => {
console.log('MCP endpoint: http://localhost:3000/mcp');
});
When auth is enabled, execute can take a second context argument and read context.user (sub, login, email, provider).
Knowledge Base
Express MCP includes a FlexSearch-backed knowledge base with three MCP tools: kb_search, kb_list, and kb_get. When you pass a name to ExpressMcp, those tools are prefixed (e.g. my-service_kb_search) so multiple MCP services can coexist in one client.
Knowledge base documents are also exposed as native MCP resources at kb://{name}/{id} when name is set, or kb://documents/{id} when unnamed. Calling agents can browse them with resources/list / resources/read while still using {name}_kb_search for full-text discovery.
import { ExpressMcp } from '@brandon-svec/express_mcp';
const expressMcp = new ExpressMcp({
name: 'my-api-server',
description: 'Internal API documentation and guides'
});
await expressMcp.addDocument('getting-started', {
title: 'Getting Started Guide',
content: 'This guide will help you get started with our API...',
tags: ['guide', 'tutorial', 'beginner'],
metadata: { category: 'documentation' }
});
// Also readable at kb://my-api-server/getting-started via resources/read
Fetch one document by plain id or by kb://{namespace}/{id} (the URI printed in the Turn-0 playbook directory)
Tool descriptions update as you add documents: available tags and your custom description are included so AI clients know what is searchable.
Disable the knowledge base with enableKnowledgeBase: false (KB tools and kb:// resources are omitted; custom registerResource playbooks still work).
Resources
Register static or read-on-demand playbooks and schemas as MCP resources. Subclass BaseResource or pass static text / blob:
import { ExpressMcp, BaseResource } from '@brandon-svec/express_mcp';
const expressMcp = new ExpressMcp({ enableKnowledgeBase: false });
expressMcp.registerResource(new BaseResource({
uri: 'playbook://incident-response',
name: 'incident-response',
title: 'Incident Response',
description: 'Pager playbook for production incidents',
text: '# Incident Response\n1. Page on-call\n2. Open a bridge',
}));
Clients discover resources with resources/list and load contents with resources/read (params.uri). Explicit registrations win over a Knowledge Base document that would map to the same URI.
Lifecycle Hooks
Register in-process hooks (no subprocesses) to intercept MCP tool calls and the optional agent. Subclass BaseHook, then call registerHook():
import { ExpressMcp, BaseHook, BaseTool } from '@brandon-svec/express_mcp';
class BlockDestructiveHook extends BaseHook {
constructor() {
super('block-destructive', ['PreToolUse', 'PermissionRequest'], {
matcher: /delete|drop/i
});
}
async execute(event) {
if (event.tool_annotations?.destructiveHint) {
return this.deny(`Blocked destructive tool: ${event.tool_name}`);
}
return this.allow();
}
}
class AnnotatedTool extends BaseTool {
constructor() {
super(
'delete_record',
'Delete a record by id',
{ type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
{ destructiveHint: true, title: 'Delete record' }
);
}
async execute({ id }) {
return { deleted: id };
}
}
const expressMcp = new ExpressMcp({ permissionMode: 'default' });
expressMcp.registerTool(new AnnotatedTool());
expressMcp.registerHook(new BlockDestructiveHook());
Event
Where
Blocking
SessionStart
New MCP session / empty agent history
No — injects additionalContext into instructions / turn
UserPromptSubmit
Agent.processMessage
Yes — can rewrite or deny the prompt
PreToolUse
MCP tools/call and agent tool loop
Yes — validate/modify args or deny (isError: true)
PermissionRequest
After PreToolUse when permissionMode is ask_for_approval, destructiveHint, or a matcher hits
Yes
PostToolUse
After successful tool execution
No — can append additionalContext
Stop
Agent final reply
Yes — can force self-correction within maxToolRounds
Denied PreToolUse/PermissionRequest results return an MCP tool result with isError: true (JSON-RPC success) so the LLM can read the policy rejection. Unexpected hook errors fail open unless the hook was constructed with { failClosed: true }.
Authentication (OAuth SSO)
Optional GitHub and/or Google login. Users receive a JWT; MCP clients send Authorization: Bearer <token> on each request.
See docs/AUTH.md for the full config reference, env vars, session stores, and OAuth provider setup.
Spark connects through Google Account Linking, not by pasting your GOOGLE_CLIENT_SECRET into Spark’s UI.
Enable auth with a Google IdP client. Register only{baseUrl}/mcp/auth/callback on that Google Cloud OAuth client (the server’s IdP callback).
Point Spark Connected Apps at your MCP HTTPS URL. Spark DCR registers oauth-redirect / oauth-redirect-sandbox / oauth-redirect-test.googleusercontent.com redirect hosts — those are trusted by default (no trustedRedirectHosts or allowAnyHttpsRedirect required for Spark).
After the user signs in, Google’s servers call your POST /mcp/token. The library returns refresh_token and echoes the wire-encoded state unchanged (required for Account Linking).
Do not add oauth-redirect*.googleusercontent.com URLs to the Google Cloud OAuth client’s authorized redirect list. See docs/AUTH.md for trustedRedirectHosts and allowAnyHttpsRedirect when integrating other agents.
Optional AI Agent
Enable an in-process Gemini agent that can call your registered tools (exposed as agent_ask by default):
const expressMcp = new ExpressMcp({
name: 'my-service',
auth: { /* auth config */ },
agent: {
enabled: true,
systemInstruction: 'You help users with this service.',
gemini: {
apiKey: process.env.GEMINI_API_KEY,
model: 'gemini-2.0-flash'
}
}
});
Requires auth by default (agent.allowUnauthenticated: true to opt out). @google/genai is an optional peer dependency.
Turn-0 domain expert manifest: When the agent is enabled, ExpressMcp appends a live domain manifest to every processMessage system instruction (identity + operational playbooks directory). It is rebuilt each turn from name, description, registered BaseResource playbooks, and knowledge-base documents — so addDocument() / registerResource() appear on the next turn without rebuilding the Agent. Set agent.includeDomainManifest: false for raw unaugmented prompts. When there is no name, no description, and no playbooks, the manifest is empty and systemInstruction is unchanged.
When exposeTool is true (default), the MCP tool {name}_agent_ask (or agent_ask when name is unset) is registered for inbound agent-to-agent delegation:
Argument
Required
Description
prompt
yes
Natural-language question, goal, or instruction
conversation_id
no
Opaque id (≤128 chars, no control characters) for multi-turn continuity. When omitted, a UUID is generated and returned
context
no
Non-empty plain object of structured caller JSON. Injected for this turn only as CALLER_CONTEXT:\n<canonical JSON>\n\n via ephemeralPrefix — never stored in history
Return value: { reply, conversation_id }. History keys are scoped per authenticated user as mcp:{user.sub|anon}:{conversation_id} so callers cannot collide across users.
The tool description is refreshed when tools are registered/unregistered or knowledge-base documents / resources change. It appends the server description (domain copy), callable tool names (Available capabilities: …), knowledge-base tags when present, and an operational playbook count when playbooks exist. Optional agent.description overrides the base description string.
Use getAgent().processMessage(historyKey, text, options) for inbound turns. Optional options.ephemeralPrefix is prepended to text for the model on this turn only (including tool rounds) and is never stored or replayed — hosts use it for working-memory fences and similar ephemeral context. Optional options.meta.traceparent parents the agent CHAIN span under an upstream TOOL/HTTP span. Optional per-turn options:
toolNames: string[] — only these registered tools are declared and callable for this turn (must pass excludeTools / toolAllowlist). An empty list omits the tools key from the Gemini request entirely (Gemini rejects functionDeclarations: [] with INVALID_ARGUMENT).
systemInstruction: string — replace the agent constructor system instruction for this turn only.
includePriorHistoryInContents: boolean — default true. When false, Gemini contents for this turn are only the current user turn (plus in-turn tool rounds); prior history is still read for SessionStart / logging and still appended at the end. Hosts that embed a compact transcript in ephemeralPrefix use this to avoid duplicating multi-turn Content[] JSON.
recordedAt: Date | number — optional timestamp stored with the history turn (also accepted by recordAssistantMessage). Defaults to new Date() at append time. One combined turn still holds user + model contents.
escalation: { toolNames, systemInstruction, resolve? } — requires toolNames (allowed catalog; must be a superset of the turn’s toolNames) and systemInstruction (full-set fallback). Adds a synthetic request_tools declaration (with tools.items.enum constrained to unloaded catalog names). When escalation is set, the agent appends an MCP CAPABILITIES catalog (Active vs Available from ToolRegistry descriptions, plus chaining / anti-guessing rules) to systemInstruction. After a successful escalate, the AVAILABLE block is omitted because request_tools is no longer declared. The model may call request_tools({ reason, tools? }): omit tools to grant the full catalog + static systemInstruction; pass tools: string[] to load those names (merged with the active set). Invalid LLM tools / empty reason return { ok: false, error, availableTools } so the model can retry; host resolve contract errors still throw. Optional resolve(requestedTools) returns { toolNames, systemInstruction } for host-controlled selective escalation. On success the functionResponse is { ok: true, tools: [{ name, description, parameters }, ...] }. Escalation grants +1maxToolRounds budget. request_tools call/response pairs are stripped from stored history (atomic pair scrub) so Gemini function-pairing stays valid on replay.
Optional agent constructor options:
historyToolTurns: 'full' | 'omit' | 'digest' — 'full' (default) stores tool-loop functionCall / functionResponse parts; 'omit' stores only the user text and final model reply so large tool payloads are not replayed; 'digest' stores one model content with a HOST_TOOLS: JSON part (from required historyToolDigest(toolName, args, result)) plus the reply. Failed calls store { ok: false, error } with error truncated to 200 characters. Turns with no tool calls store user + reply only. request_tools is never included in the digest.
historyToolDigest — required when historyToolTurns is 'digest'; must return a plain object.
historyMaxTurns — when using the default in-memory history, keep at most this many turns after TTL pruning (oldest first). Cannot be set together with a custom agent.history.
excludeTools: string[] — additional tool names the agent must not call (merged with built-in session / agent_ask exclusions).
description: string — custom base description for the agent_ask MCP tool (before domain / capabilities / tag enrichment).
includeDomainManifest: boolean — default true. When true, appends the Turn-0 domain expert manifest (service identity + playbooks directory with governing tools) to the system instruction on every turn. Set false to leave systemInstruction unaugmented.
processMessage also accepts optional historyUserText: when set, that string is stored for the user turn instead of text (the model still sees text, optionally with ephemeralPrefix).
httpRouter({ mcpPath, rootAliases, sessionOptions }): set rootAliases: false for a secondary mount (e.g. /mcp/admin) so it does not register site-root OAuth AS aliases that would collide with the primary. Path-based discovery (/.well-known/oauth-authorization-server{mcpPath}) is always registered. Auth middleware is attached only to exact / MCP routes so a longer sibling path is not intercepted.
The default in-memory history store (InMemoryHistoryStore) exposes:
get(key) — flattened Gemini Content[] for replay (timestamps stripped).
getTurns(key) — pruned Array<{ recordedAt: Date, contents }> as detached copies (safe to .reverse() without mutating store order).
append(key, contents, { recordedAt? }) — optional recordedAt as a Date or epoch millis (defaults to new Date()).
Package exports also include formatTurnsTranscript(turns, { now, userLabel, modelLabel }) (newest-first relative transcript; reverses turns and contents; skips non-text and HOST_TOOLS: digest parts), buildCapabilitiesCatalog({ activeTools, availableTools }), and buildDomainExpertManifest({ serverName, serviceDescription, agentDescription, playbooks }) for hosts that need the helpers outside processMessage.
For host-initiated agent speech (proactive reminders, notifications) that must appear in the next turn’s conversation history without calling the LLM, use getAgent().recordAssistantMessage(historyKey, text, { recordedAt? }). That method requires a history store and throws if none is configured. When recorded model turns leave history starting with a model role, processMessage prepends a synthetic user [continued] turn before calling Gemini so contents remain valid. Schema and tool execution errors are returned to the model as { ok: false, error } functionResponses so further maxToolRounds can fix args and retry (same recovery Cursor gets over MCP JSON-RPC).
Set loggerOptions.level to trace to log the exact model request (contents, systemInstruction, toolDeclarations) plus a per-content size breakdown before each generate. Trace payloads include raw user content. At info, each completed turn logs character totals (contentsChars, systemInstructionChars, toolDeclarationChars, historyTurns, toolCount, escalated) without the request body.
API Reference
ExpressMcp
const expressMcp = new ExpressMcp({
name: 'my-service', // Instance name (tool prefixing + logger name)
description: 'My API docs', // Appended to knowledge base tool descriptions
enableKnowledgeBase: true, // Register kb_* tools (default: true)
loggerOptions: {
enabled: true,
level: 'info',
name: 'express-mcp'
},
logger: customLoggerInstance, // Optional; overrides loggerOptions
auth: { /* see docs/AUTH.md */ },
agent: { /* optional; see above */ },
telemetry: { /* see docs/TELEMETRY.md */ }
});
Tool name prefixing
When name is set, knowledge base tools become {name}_kb_search, {name}_kb_list, {name}_kb_get. Use a unique name per service so clients like Cursor can route calls correctly when multiple MCP servers are connected.
Custom tools from registerTool() are not prefixed by default. To prefix a custom tool:
close() — Drain telemetry batch queue and destroy keep-alive sockets (call on process shutdown when telemetry is enabled)
router() — MCP-only Express router
httpRouter() — OAuth + MCP when auth is enabled
Optional constructor permissionMode ('default' | 'ask_for_approval') controls when PermissionRequest hooks run in addition to destructiveHint / matcher matches.
Documents accept optional playbook fields: summary (string), tools (string[] of governed tool names), and relatedDocs (string[]). When summary is omitted, the first clean non-heading paragraph is extracted (≤180 chars). When tools is omitted, content is scanned for known registered tool names (identifier-safe, longest-first).
kb_search scores matches across tools (+3), title (+3), summary (+2), tags (+2), and content (+1) so documentation is discoverable by tool name or semantic intent.
Resources
registerResource(resource) — Register a BaseResource (URIs are not name-prefixed)
BaseResource accepts optional summary and tools for the operational playbooks directory (merged with KB documents via resourceRegistry.getPlaybooksManifest()).
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Fragen
Wie installiere ich @brandon Svec/express?
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Benötigt @brandon Svec/express einen API-Schlüssel?
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
Welchen Transport verwendet @brandon Svec/express?
@brandon Svec/express läuft lokal über stdio.
Wann wurde @brandon Svec/express zuletzt geprüft?
Zuletzt geprüft: 2026-11-10. Add MCP tools, OAuth, and a knowledge base to any Express app so AI clients can call your APIs