Build complete MCP servers
Publish typed MCP tools, prompts, resources, elicitation, feedback, OAuth-native clients, and stricter secondary endpoints from an AbsoluteJS application.
@absolutejs/mcpv0.11.3betaAIRemote MCP endpoint for Elysia servers: bring your tools and authorization, the JSON-RPC protocol and OAuth discovery come done correctly.
Serves a remote Model Context Protocol endpoint (streamable HTTP, stateless) from a typed tool, prompt, and resource registry as an Elysia plugin. You supply which tools to expose and how to authorize a request into a caller; the package owns the JSON-RPC protocol, protocol-version negotiation, RFC 9728 discovery metadata, and the 401 challenge that points clients at your authorization server. Nothing in it depends on a model, and the tool shape is structurally compatible with the AIToolMap from @absolutejs/ai, so an existing AI tool registry serves over MCP without conversion.
bun add @absolutejs/mcpMCP tool discovery preserves the OpenID AuthZEN COAZ coaz marker and x-coaz-mapping JSON Schema extension end to end. Use @absolutejs/policy to validate and evaluate the mapping before dispatching an authorized tool call.
Serve a remote Model Context Protocol endpoint — streamable HTTP, stateless — from a tool/prompt/resource registry. You supply which tools to expose and how to authorize a request into a caller; the package owns the JSON-RPC protocol, protocol-version negotiation, RFC 9728 discovery metadata, and the 401 challenge that lets a client find your authorization server. The default negotiated revision is the current finalized 2025-11-25 specification; older finalized revisions remain available when explicitly requested.
Tools carrying manifest contract 2 authorization metadata fail closed unless an agency enforcement point is configured. Every call becomes an exact-input action request; allowed calls execute through a short-lived single-use lease and produce a receipt. Requestable denials return an absolute.action_decision payload containing the action id for an approval workflow.
Agency is a required host peer (>=0.7.1 <0.8.0) and is externalized from the MCP build. This guarantees that every transport uses the host's one action ledger instead of embedding a private enforcement runtime. The package tests against exactly 0.7.1; a new Agency minor requires an explicit compatibility release.
The package implements native MCP 2025-11-25 task augmentation: execution.taskSupport, client-requested task creation, tasks/get, tasks/result, authorization-bound tasks/list, and terminal-safe tasks/cancel. It also retains the older io.modelcontextprotocol/tasks SEP-2663 wire shape only when an older protocol revision is negotiated.
Clients can use callToolAsTask, then getTask, listTasks, cancelTask, and getTaskResult. Task status never exposes the stored result or authorization key; the final result is returned only by tasks/result with required io.modelcontextprotocol/related-task metadata.
For multi-instance production deployments, use createPostgresMcpTaskStore() and createPostgresMcpSessionStore() after applying mcpPostgresSchemaSql(). Task updates and cancellation protect terminal states in the database, task reads enforce TTL, and session access atomically extends only unexpired sessions. The adapters accept a structural SQL client and do not require a particular PostgreSQL driver.
Nothing here depends on a model. The tool shape is structurally compatible with @absolutejs/ai's AIToolMap, so an AI tool registry serves over MCP without conversion — but any typed tool registry works.
Peer dependency: elysia.
That is a complete member endpoint. GET /mcp returns 405, POST /mcp speaks JSON-RPC, and GET /.well-known/oauth-protected-resource[/mcp] serves the discovery metadata.
Everything beyond tools is a hook — the package ships no opinion about billing, storage, or auditing.
The meta scratchpad
Each tools/call gets a fresh meta object shared between tools, beforeCall, and onCall. A tool handler can record what it touched, and your audit hook can read it back:
A connected AI client renders no UI for your server. There is no button for the user to press, so when they say _"that was wrong"_ the only path back to you is the model relaying it. Every MCP server has this hole, and every one of them hand-rolls the same two tools.
FEEDBACK_INSTRUCTIONS is the load-bearing half. Without it a model treats a complaint as something to apologise for, and the signal dies where it was spoken.
A tool that can't finish without something only the user knows can ask them (elicitation/create) and wait for the answer.
requestedSchema is a flat object of primitives (string / number / integer / boolean / enum) — the spec restricts it so any client can render a form. The answer is accept (with content), decline (they said no), cancel (they dismissed it), or unsupported (this client can't ask anyone — check canElicit and take another path). Never fabricate an answer for the user; the spec also forbids eliciting sensitive information.
For credentials, third-party OAuth, or payment flows, use mode: "url" with a unique elicitationId and HTTPS URL. The client advertises form and URL modes separately, never prefetches the URL, and returns only the user's consent—not credentials or page contents. Tool handlers can check canElicitUrl before starting the flow. The server rejects non-HTTPS URLs except localhost development URLs and rejects URLs containing embedded credentials.
The trade-off, stated plainly. Elicitation is the one MCP feature a stateless server cannot do: the question goes out on the SSE stream of an in-flight tools/call, and the client answers on a _separate_ HTTP POST. Two requests have to meet, so the endpoint becomes session-stateful (Mcp-Session-Id). Leave elicitation off — the default — and nothing changes: the server stays stateless, tools/call keeps answering with a plain JSON body, and only tools marked mayElicit ever stream.
Running more than one instance. Behind one server the defaults handle it. Behind several, two different things break, and each has a seam:
Supply neither and run a single instance (or pin sessions). Supply both and elicitation is safe behind a load balancer with no sticky routing — there is a test for exactly that: instance A asks, the answer lands on B, the bus carries it back, and A's call finishes.
AbsoluteJS already ships both production transports. PostgreSQL is the default; Redis is an optional at-most-once fan-out optimization:
The channel is only coordination: durable jobs and side effects belong in @absolutejs/queue / @absolutejs/execution, not Redis pub/sub or NOTIFY.
Consuming a server that elicits? Pass onElicit to createMcpClient — that is what declares the capability, and what the package uses to answer. Omit it and servers are told you cannot ask anyone.
mcpServer is per-endpoint, so an admin console is the same call with a different scope, a stricter authorize (role + MFA + a kill switch, re-checked live), a rate-limit beforeCall, and an audit onCall:
Only one endpoint per app should set serveRootMetadata (the un-suffixed alias).
createMcpOAuthProvider handles the current MCP authorization flow without coupling to an identity vendor: RFC 9728 protected-resource discovery, OAuth or OIDC authorization-server discovery, Client ID Metadata Document identifiers, PKCE S256, resource indicators, refresh rotation, incremental scope challenges, and optional DPoP proofs. The host owns the user interaction and token store.
The client retries a 401 only once and only after the authorization provider reports success. Metadata fetches require HTTPS, reject redirects, enforce byte limits, verify issuer/resource identity, and use the injected fetch so production deployments can route discovery through @absolutejs/egress.
POST speaks JSON-RPC with plain JSON responses and no session state by default, so the endpoint scales like any other stateless route.
verifyBearer runs the standard OAuth access-token checks, and the plugin serves RFC 9728 protected-resource metadata plus the 401 challenge that lets clients discover your authorization server.
beforeCall can refuse a single call (credits, rate limits) with a message the model relays, onCall audits every call, and a per-request meta scratchpad carries data between tool handlers and hooks.
Tools marked mayElicit can ask the user a question mid-call and await the answer; opt-in session state plus pluggable store and bus seams make it safe behind a load balancer with no sticky routing.
feedbackTools and FEEDBACK_INSTRUCTIONS give connected AI clients a channel to report problems and relay user feedback, the signal every MCP server otherwise hand-rolls or loses.
Server-side prompt definitions and readable resources are plain hooks, and createMcpClient consumes remote MCP servers, including answering their elicitation requests via onElicit.
Tools with manifest-contract authorization metadata fail closed unless Agency enforcement is configured. Allowed calls bind the exact input to a short-lived single-use execution lease and produce a receipt.
Native MCP 2025-11-25 tasks support creation, get, result, authorization-bound listing, cancellation, TTL, and terminal-state protection with memory or PostgreSQL stores.
Protected tools bind authorization to the exact action and consume a short-lived execution lease before effects occur.
MCP 2025-11-25 tasks let long-running tools survive transport and process boundaries.
Outcomes
Publish typed MCP tools, prompts, resources, elicitation, feedback, OAuth-native clients, and stricter secondary endpoints from an AbsoluteJS application.
Route consequential tool calls through Agency decisions and model long-running work as durable tasks instead of keeping requests open indefinitely.
Hardening checklist
Follow in order
Working example for Define an endpoint.
import { Elysia } from "elysia";
import { mcpServer, verifyBearer } from "@absolutejs/mcp";
import { verifyJwt } from "@absolutejs/auth"; // or any JWT verifier
type Caller = { userId: string };
const server = new Elysia().use(
mcpServer<Caller>({
path: "/mcp",
issuer: "https://your.app",
serverInfo: { name: "your-app", title: "Your App", version: "1.0.0" },
instructions: "What the model should know about this server.",
scopesSupported: ["openid", "mcp"],
serveRootMetadata: true,
// You decide who is allowed in. verifyBearer does the standard OAuth
// access-token checks; add your own (billing, role, MFA) on top.
authorize: async (request) => {
const token = await verifyBearer({
audience: "https://your.app/mcp",
request,
issuer: "https://your.app",
requiredScope: "mcp",
verify: (jwt) => verifyJwt(jwt, publicJwk),
});
if ("error" in token) return { ok: false, reason: token.error };
return { ok: true, caller: { userId: token.subject } };
},
// Called once per request; build the tools for this caller.
tools: ({ caller }) => buildToolsFor(caller.userId),
}),
);Tools carrying manifest contract 2 authorization metadata fail closed unless an agency enforcement point is configured. Every call becomes an exact-input action request; allowed calls execute through a short-lived single-use lease and produce a receipt. Requestable denials return an absolute.action_decision payload containing the action id for an approval workflow.
import { createAgency, createMemoryAgencyStore } from "@absolutejs/agency";
const agency = createAgency({ policy, store: createMemoryAgencyStore() });
mcpServer<Caller>({
agency: {
enforcement: agency,
resolveActor: ({ caller, scopes }) => ({
agentId: caller.agentId,
delegationId: caller.delegationId,
scopes,
userId: caller.userId,
}),
},
// normal MCP config…
});The package implements native MCP 2025-11-25 task augmentation: execution.taskSupport, client-requested task creation, tasks/get, tasks/result, authorization-bound tasks/list, and terminal-safe tasks/cancel. It also retains the older io.modelcontextprotocol/tasks SEP-2663 wire shape only when an older protocol revision is negotiated.
tasks: {
authorizationKey: (caller) => caller.userId,
shouldCreate: ({ name }) => name === "long_running_report",
store: createMemoryMcpTaskStore(), // use a durable shared store in production
ttlMs: 60 * 60 * 1000,
}
tools: () => ({
long_running_report: {
taskSupport: "optional", // "required" and "forbidden" are also supported
// normal tool definition…
},
})A complete MCP endpoint: POST /mcp speaks JSON-RPC and the RFC 9728 discovery metadata is served automatically.
import { Elysia } from 'elysia';
import { mcpServer, verifyBearer } from '@absolutejs/mcp';
type Caller = { userId: string };
const server = new Elysia().use(
mcpServer<Caller>({
path: '/mcp',
issuer: 'https://your.app',
serverInfo: { name: 'your-app', title: 'Your App', version: '1.0.0' },
instructions: 'What the model should know about this server.',
scopesSupported: ['openid', 'mcp'],
serveRootMetadata: true,
// You decide who is allowed in. verifyBearer does the standard
// OAuth access-token checks; add your own on top.
authorize: async (request) => {
const token = await verifyBearer({
request,
issuer: 'https://your.app',
requiredScope: 'mcp',
verify: (jwt) => verifyJwt(jwt, publicJwk)
});
if ('error' in token) return { ok: false, reason: token.error };
return { ok: true, caller: { userId: token.subject } };
},
// Called once per request; build the tools for this caller.
tools: ({ caller }) => buildToolsFor(caller.userId)
})
);Guard calls, audit them, and give the connected AI client a feedback channel back to you.
import {
FEEDBACK_INSTRUCTIONS,
feedbackTools,
mcpServer
} from '@absolutejs/mcp';
mcpServer<Caller>({
// ...as above
instructions: `${myInstructions} ${FEEDBACK_INSTRUCTIONS}`,
// Refuse a single call before it runs; the message comes back as
// an isError tool result the model can relay, not a crash.
beforeCall: async ({ caller }) =>
(await outOfCredits(caller))
? { block: 'Out of credits this cycle.' }
: undefined,
// Audit every call. meta carries whatever the tool handler wrote.
onCall: ({ caller, name, ok, meta }) =>
recordCall({ caller, name, ok, touched: meta.touched }),
tools: ({ caller }) => ({
...myTools(caller),
...feedbackTools({
caller,
store: {
reportProblem: ({ caller, report }) => file(caller, report),
submitFeedback: ({ caller, feedback }) => record(caller, feedback)
}
})
})
});Enforce consequential tools through the host Agency ledger and persist long-running MCP tasks in PostgreSQL for multi-instance deployments.
import { createAgency, createMemoryAgencyStore } from '@absolutejs/agency';
import { createPostgresMcpTaskStore, mcpServer } from '@absolutejs/mcp';
const agency = createAgency({ policy, store: createMemoryAgencyStore() });
mcpServer<Caller>({
agency: {
enforcement: agency,
resolveActor: ({ caller, scopes }) => ({
agentId: caller.agentId,
delegationId: caller.delegationId,
scopes,
userId: caller.userId
})
},
tasks: {
authorizationKey: (caller) => caller.userId,
shouldCreate: ({ name }) => name === 'long_running_report',
store: createPostgresMcpTaskStore({ sql }),
ttlMs: 60 * 60 * 1000
},
tools: () => ({
long_running_report: { taskSupport: 'optional', ...reportTool }
})
});Search the declarations exported by the current package type files. Expand a symbol to inspect its source-backed signature.
Current package surface
Import surface · click to copy