AbsoluteJS

MCP

@absolutejs/mcpv0.11.3betaAI

Remote 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.

#Installation

BASH
bun add @absolutejs/mcp

#Capabilities

Overview

MCP 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.

Agent action enforcement

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.

Durable Tasks

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.

Show 2 more

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.

Define an endpoint

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.

Guards, prompts, resources

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:

Feedback: the channel a client can't give you

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.

Elicitation: ask the user a question mid-call

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.

Show 6 more

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.

A second, stricter endpoint

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).

OAuth-native MCP client

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.

Stateless streamable HTTP

POST speaks JSON-RPC with plain JSON responses and no session state by default, so the endpoint scales like any other stateless route.

OAuth bearer auth and discovery

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.

Per-call guards and audit

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.

Mid-call elicitation

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.

Built-in feedback tools

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.

Prompts, resources, and client

Server-side prompt definitions and readable resources are plain hooks, and createMcpClient consumes remote MCP servers, including answering their elicitation requests via onElicit.

Agency action enforcement

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.

Durable MCP tasks

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 tool sequence

Protected tools bind authorization to the exact action and consume a short-lived execution lease before effects occur.

  1. Receive
    Validate the MCP request, caller, schema, and declared action.
  2. Authorize
    Ask Agency to approve the canonical action binding.
  3. Fence
    Issue and consume a single-use execution lease.
  4. Execute
    Run the handler and persist its receipt.
  5. Respond
    Return a result or a durable task reference.

#Durable task lifecycle

MCP 2025-11-25 tasks let long-running tools survive transport and process boundaries.

  1. Create
    Create a task with caller ownership, authorization binding, and TTL.
  2. Persist
    Persist task and session state in a durable store.
  3. Observe
    Poll, list, or subscribe without losing ownership checks.
  4. Finish
    Complete, fail, expire, or cancel with a terminal record.

Outcomes

What you can build

Build complete MCP servers

Publish typed MCP tools, prompts, resources, elicitation, feedback, OAuth-native clients, and stricter secondary endpoints from an AbsoluteJS application.

Govern and persist agent work

Route consequential tool calls through Agency decisions and model long-running work as durable tasks instead of keeping requests open indefinitely.

Hardening checklist

Production guidance

Secure the protocol boundaryAuthenticate before tool execution, validate every input, separate endpoint trust levels, persist durable tasks, bound scratchpad data, and retain authorization and execution evidence.

Follow in order

Troubleshooting path

1
A tool call was rejected or stalled
Inspect endpoint discovery, OAuth metadata, guard decisions, parsed tool input, Agency action state, durable task state, and the final MCP result separately.

#Define an endpoint

Partial snippet

Working example for Define an endpoint.

TS
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),
  }),
);

#Agent action enforcement

Partial snippet

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.

TS
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…
});

#Durable Tasks

Partial snippet

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.

TS
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…
  },
})

#Quick Start

Partial snippet

A complete MCP endpoint: POST /mcp speaks JSON-RPC and the RFC 9728 discovery metadata is served automatically.

TS
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)
	})
);

#Guards, Audit, and Feedback

Partial snippet

Guard calls, audit them, and give the connected AI client a feedback channel back to you.

TS
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)
			}
		})
	})
});

#Governed Durable Tasks

Partial snippet

Enforce consequential tools through the host Agency ledger and persist long-running MCP tasks in PostgreSQL for multi-instance deployments.

TS
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 }
	})
});
Multiple endpoints
mcpServer is per-endpoint: mount a second, stricter instance (different path, scopes, authorize, and guards) for an admin surface. Only one endpoint per app should set serveRootMetadata.
Beta API
The package is pre-1.0; the elicitation and session seams in particular may evolve, so pin an exact version.

#API reference

Search the declarations exported by the current package type files. Expand a symbol to inspect its source-backed signature.

80 symbols
verifyBearerexportPermalink
TS
verifyBearer
Exported from @absolutejs/mcp

Current package surface

What ships today

@absolutejs/mcpv0.11.3 · betaAInpmSource
3entry points81symbols

Import surface · click to copy