@adonis-agora/agent 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @adonis-agora/agent
 
+## 0.19.0
+
+### Minor Changes
+
+- [`9a91190`](https://github.com/DavideCarvalho/adonis-agent/commit/9a91190936f24f912ccb756c58f490381f2b13c7) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Add an MCP (Model Context Protocol) endpoint that exposes the agent's ToolRegistry over Streamable
+  HTTP.
+
+  - New `./mcp` subpath: `defineMcpConfig`, `createMcpServer`, and two auth strategies — `authKitAuth()`
+    (OAuth OIDC via `@adonis-agora/authkit-server`, resolved lazily) and `apiKeyAuth()` (constant-time
+    key compare). The acting `Actor` resolves from the verified auth and gates `tools/list` /
+    `tools/call` through the same role-checked registry the agent loop uses (fail-closed).
+  - New `./mcp_provider` subpath: an Adonis provider that mounts `POST|GET|DELETE /mcp` plus
+    `GET /.well-known/oauth-protected-resource/mcp` (RFC 9728 metadata when OAuth is configured), with
+    per-session Streamable HTTP transports.
+  - `configure` publishes `config/mcp.ts` via the new `config/mcp.stub`.
+
+  The published `dist` ships `./mcp` and `./mcp_provider` export maps (mirroring `./agent_provider`).
+
 ## 0.18.0
 
 ### Minor Changes

package/dist/configure.d.ts

@@ -7,11 +7,12 @@ import type Configure from '@adonisjs/core/commands/configure';
  *    build/dev time (the provider imports it instead of scanning at runtime; it falls back to the
  *    runtime scan when the barrel is absent);
  * 3. publishes `config/agent.ts`;
- * 4. publishes the Lucid migration for the five agent tables (run `node ace migration:run`; delete it
+ * 4. publishes `config/mcp.ts` (the MCP endpoint config; the MCP provider is separate);
+ * 5. publishes the Lucid migration for the five agent tables (run `node ace migration:run`; delete it
  *    if you only use the in-memory store);
- * 5. publishes the additive run-tracking migration (`agent_run` table + `run_id` columns) — run it
+ * 6. publishes the additive run-tracking migration (`agent_run` table + `run_id` columns) — run it
  *    after the base migration; delete it with the base one if you only use the in-memory store;
- * 6. publishes the pgvector migration for the RAG chunk table (Postgres + pgvector only; delete it
+ * 7. publishes the pgvector migration for the RAG chunk table (Postgres + pgvector only; delete it
  *    unless you use `retrievers.pgvector({...})`).
  */
 export declare function configure(command: Configure): Promise<void>;

package/dist/configure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"configure.d.ts","sourceRoot":"","sources":["../configure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,mCAAmC,CAAC;AAG/D;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,SAAS,iBAajD"}
+{"version":3,"file":"configure.d.ts","sourceRoot":"","sources":["../configure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,mCAAmC,CAAC;AAG/D;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,SAAS,iBAcjD"}

package/dist/configure.js

@@ -7,11 +7,12 @@ import { stubsRoot } from './stubs/main.js';
  *    build/dev time (the provider imports it instead of scanning at runtime; it falls back to the
  *    runtime scan when the barrel is absent);
  * 3. publishes `config/agent.ts`;
- * 4. publishes the Lucid migration for the five agent tables (run `node ace migration:run`; delete it
+ * 4. publishes `config/mcp.ts` (the MCP endpoint config; the MCP provider is separate);
+ * 5. publishes the Lucid migration for the five agent tables (run `node ace migration:run`; delete it
  *    if you only use the in-memory store);
- * 5. publishes the additive run-tracking migration (`agent_run` table + `run_id` columns) — run it
+ * 6. publishes the additive run-tracking migration (`agent_run` table + `run_id` columns) — run it
  *    after the base migration; delete it with the base one if you only use the in-memory store;
- * 6. publishes the pgvector migration for the RAG chunk table (Postgres + pgvector only; delete it
+ * 7. publishes the pgvector migration for the RAG chunk table (Postgres + pgvector only; delete it
  *    unless you use `retrievers.pgvector({...})`).
  */
 export async function configure(command) {
@@ -22,6 +23,7 @@ export async function configure(command) {
         rcFile.addAssemblerHook('init', '@adonis-agora/agent/hooks/tools');
     });
     await codemods.makeUsingStub(stubsRoot, 'config/agent.stub', {});
+    await codemods.makeUsingStub(stubsRoot, 'config/mcp.stub', {});
     await codemods.makeUsingStub(stubsRoot, 'database/migrations/create_agent_tables.stub', {});
     await codemods.makeUsingStub(stubsRoot, 'database/migrations/create_agent_run_tracking.stub', {});
     await codemods.makeUsingStub(stubsRoot, 'database/migrations/create_agent_rag_chunks.stub', {});

package/dist/configure.js.map

@@ -1 +1 @@
-{"version":3,"file":"configure.js","sourceRoot":"","sources":["../configure.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAkB;IAChD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,cAAc,EAAE,CAAC;IAEhD,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,WAAW,CAAC,oCAAoC,CAAC,CAAC;QACzD,mGAAmG;QACnG,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,iCAAiC,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,mBAAmB,EAAE,EAAE,CAAC,CAAC;IACjE,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,8CAA8C,EAAE,EAAE,CAAC,CAAC;IAC5F,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,oDAAoD,EAAE,EAAE,CAAC,CAAC;IAClG,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,kDAAkD,EAAE,EAAE,CAAC,CAAC;AAClG,CAAC"}
+{"version":3,"file":"configure.js","sourceRoot":"","sources":["../configure.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAkB;IAChD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,cAAc,EAAE,CAAC;IAEhD,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,WAAW,CAAC,oCAAoC,CAAC,CAAC;QACzD,mGAAmG;QACnG,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,iCAAiC,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,mBAAmB,EAAE,EAAE,CAAC,CAAC;IACjE,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,iBAAiB,EAAE,EAAE,CAAC,CAAC;IAC/D,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,8CAA8C,EAAE,EAAE,CAAC,CAAC;IAC5F,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,oDAAoD,EAAE,EAAE,CAAC,CAAC;IAClG,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,kDAAkD,EAAE,EAAE,CAAC,CAAC;AAClG,CAAC"}

package/dist/providers/mcp_provider.d.ts

@@ -0,0 +1,22 @@
+import type { ApplicationService } from '@adonisjs/core/types';
+/**
+ * Wires the agent's {@link ToolRegistry} to the outside world over the Model Context Protocol
+ * (Streamable HTTP). Reads `config/mcp.ts` and mounts:
+ *
+ * - `POST|GET|DELETE {path}` — the MCP endpoint (initialize/session resume, SSE stream, close).
+ * - `GET /.well-known/oauth-protected-resource{path}` — RFC 9728 protected-resource metadata, mounted
+ *   only when `auth.oauth` is set, so MCP clients can discover how to authenticate.
+ *
+ * Every request is authenticated: the bearer token is verified via `config.auth` (e.g. `authKitAuth()`),
+ * the resolved actor attached to the transport's `AuthInfo`, and `tools/list` / `tools/call` run against
+ * the SAME `ToolRegistry` singleton the agent loop uses — so a role-checked tool stays role-checked, and
+ * a fail-closed gate stays fail-closed, no matter the surface.
+ */
+export default class McpProvider {
+    #private;
+    protected app: ApplicationService;
+    constructor(app: ApplicationService);
+    boot(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=mcp_provider.d.ts.map

package/dist/providers/mcp_provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp_provider.d.ts","sourceRoot":"","sources":["../../providers/mcp_provider.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAe/D;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,OAAO,OAAO,WAAW;;IAIlB,SAAS,CAAC,GAAG,EAAE,kBAAkB;gBAAvB,GAAG,EAAE,kBAAkB;IAEvC,IAAI;IAsCJ,QAAQ;CA+Kf"}

package/dist/providers/mcp_provider.js

@@ -0,0 +1,229 @@
+import { randomUUID } from 'node:crypto';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { DefaultToolAuthorizer } from '../src/authorizer.js';
+import { resolveMcpAuth } from '../src/mcp/auth.js';
+import { createMcpServer } from '../src/mcp/server.js';
+import { ToolRegistry } from '../src/tool-registry.js';
+/**
+ * Wires the agent's {@link ToolRegistry} to the outside world over the Model Context Protocol
+ * (Streamable HTTP). Reads `config/mcp.ts` and mounts:
+ *
+ * - `POST|GET|DELETE {path}` — the MCP endpoint (initialize/session resume, SSE stream, close).
+ * - `GET /.well-known/oauth-protected-resource{path}` — RFC 9728 protected-resource metadata, mounted
+ *   only when `auth.oauth` is set, so MCP clients can discover how to authenticate.
+ *
+ * Every request is authenticated: the bearer token is verified via `config.auth` (e.g. `authKitAuth()`),
+ * the resolved actor attached to the transport's `AuthInfo`, and `tools/list` / `tools/call` run against
+ * the SAME `ToolRegistry` singleton the agent loop uses — so a role-checked tool stays role-checked, and
+ * a fail-closed gate stays fail-closed, no matter the surface.
+ */
+export default class McpProvider {
+    app;
+    /** Live session transports, keyed by MCP session id (per-provider in-memory state). */
+    #transports = new Map();
+    constructor(app) {
+        this.app = app;
+    }
+    async boot() {
+        const config = this.app.config.get('mcp', {});
+        const registry = await this.app.container.make(ToolRegistry);
+        const defaultRoles = config.defaultRoles ?? ['ADMIN'];
+        const authorizer = config.authorizer ?? new DefaultToolAuthorizer(defaultRoles);
+        const auth = config.auth !== undefined ? await resolveMcpAuth(config.auth, { app: this.app }) : undefined;
+        // The actor fallback for open/dev mode (no `auth`): a fixed identity, or fail-closed (reject).
+        const openActor = config.actor;
+        const router = await this.app.container.make('router');
+        const path = (config.path ?? 'mcp').replace(/^\/+|\/+$/g, '');
+        const route = `/${path}`;
+        router.post(route, (ctx) => this.#handlePost(ctx, config, registry, authorizer, auth, openActor));
+        router.get(route, (ctx) => this.#handleGet(ctx, auth, openActor));
+        router.delete(route, (ctx) => this.#handleDelete(ctx, auth, openActor));
+        if (auth?.oauth) {
+            const oauth = auth.oauth;
+            const metadataPath = `/.well-known/oauth-protected-resource/${path}`;
+            router.get(metadataPath, async (ctx) => {
+                // `oauth` may be lazy (authkit needs a fully booted app to resolve) — resolve it on request.
+                const meta = typeof oauth === 'function' ? await oauth() : oauth;
+                const origin = `${ctx.request.protocol()}://${ctx.request.headers().host ?? 'localhost'}`;
+                return ctx.response.json({
+                    resource: `${origin}/${path}`,
+                    authorization_servers: [meta.issuer],
+                    scopes_supported: meta.scopesSupported,
+                    resource_name: meta.resourceName,
+                });
+            });
+        }
+    }
+    async shutdown() {
+        await Promise.all([...this.#transports.values()].map((transport) => transport.close()));
+        this.#transports.clear();
+    }
+    // ── auth helpers ──────────────────────────────────────────────────────────
+    /**
+     * Verify the request's `Authorization: Bearer` token against the configured auth, or fall back to the
+     * open-mode `actor`. Returns the `AuthInfo` to attach to the transport, or `null` to reply 401.
+     */
+    async #authenticate(ctx, auth, openActor) {
+        const header = ctx.request.header('authorization');
+        const token = header?.startsWith('Bearer ') ? header.slice(7).trim() : undefined;
+        if (auth !== undefined) {
+            if (!token) {
+                ctx.response.status(401).json({ error: 'missing bearer token' });
+                return null;
+            }
+            try {
+                return await auth.verify(token);
+            }
+            catch (error) {
+                ctx.response
+                    .status(401)
+                    .json({ error: error instanceof Error ? error.message : 'unauthorized' });
+                return null;
+            }
+        }
+        if (openActor !== undefined) {
+            return { token: '', clientId: '', scopes: [], extra: { actor: openActor } };
+        }
+        ctx.response
+            .status(401)
+            .json({ error: 'unauthorized: no auth configured and no fallback actor' });
+        return null;
+    }
+    // ── route handlers ────────────────────────────────────────────────────────
+    async #handlePost(ctx, config, registry, authorizer, auth, openActor) {
+        const req = ctx.request.request;
+        const res = ctx.response.response;
+        const body = ctx.request.all();
+        const sessionId = ctx.request.header('mcp-session-id');
+        const authInfo = await this.#authenticate(ctx, auth, openActor);
+        if (authInfo === null)
+            return;
+        req.auth = authInfo;
+        try {
+            let transport;
+            if (sessionId && this.#transports.has(sessionId)) {
+                // Session resume — reuse the existing transport (already connected to its own server).
+                transport = this.#transports.get(sessionId);
+                await transport.handleRequest(req, res, body);
+            }
+            else if (!sessionId && isInitializeRequest(body)) {
+                // New session — create transport + server, connect, then handle so responses flow through it.
+                transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                    onsessioninitialized: (sid) => {
+                        if (transport)
+                            this.#transports.set(sid, transport);
+                    },
+                });
+                transport.onclose = () => {
+                    const sid = transport?.sessionId;
+                    if (sid && this.#transports.get(sid) === transport) {
+                        this.#transports.delete(sid);
+                    }
+                };
+                const server = createMcpServer({
+                    name: config.name,
+                    version: config.version,
+                    registry,
+                    policy: authorizer,
+                    ...(config.allowedTools !== undefined ? { allowedTools: config.allowedTools } : {}),
+                    actorFromAuth: actorFromAuthInfo,
+                });
+                await server.connect(transport);
+                await transport.handleRequest(req, res, body);
+            }
+            else {
+                res.statusCode = 400;
+                res.setHeader('content-type', 'application/json');
+                res.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    error: { code: -32000, message: 'Bad Request: no valid session ID' },
+                    id: null,
+                }));
+            }
+        }
+        catch (error) {
+            if (!res.headersSent) {
+                res.statusCode = 500;
+                res.setHeader('content-type', 'application/json');
+                res.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32603,
+                        message: error instanceof Error ? error.message : 'Internal error',
+                    },
+                    id: null,
+                }));
+            }
+        }
+        await this.#awaitFinish(res);
+    }
+    async #handleGet(ctx, auth, openActor) {
+        const req = ctx.request.request;
+        const res = ctx.response.response;
+        const sessionId = ctx.request.header('mcp-session-id');
+        const authInfo = await this.#authenticate(ctx, auth, openActor);
+        if (authInfo === null)
+            return;
+        req.auth = authInfo;
+        const transport = sessionId ? this.#transports.get(sessionId) : undefined;
+        if (transport === undefined) {
+            res.statusCode = 400;
+            res.end('Invalid or missing session ID');
+            await this.#awaitFinish(res);
+            return;
+        }
+        await transport.handleRequest(req, res);
+        await this.#awaitFinish(res);
+    }
+    async #handleDelete(ctx, auth, openActor) {
+        const req = ctx.request.request;
+        const res = ctx.response.response;
+        const sessionId = ctx.request.header('mcp-session-id');
+        const authInfo = await this.#authenticate(ctx, auth, openActor);
+        if (authInfo === null)
+            return;
+        req.auth = authInfo;
+        const transport = sessionId ? this.#transports.get(sessionId) : undefined;
+        if (transport === undefined) {
+            res.statusCode = 400;
+            res.end('Invalid or missing session ID');
+            await this.#awaitFinish(res);
+            return;
+        }
+        await transport.handleRequest(req, res);
+        await this.#awaitFinish(res);
+    }
+    /** Resolve only when the raw response is finished so Adonis doesn't try to handle the response again. */
+    #awaitFinish(res) {
+        return new Promise((resolve) => {
+            res.on('finish', () => resolve());
+            res.on('close', () => resolve());
+        });
+    }
+}
+/**
+ * Read the acting {@link Actor} from the transport's verified `AuthInfo` — the auth strategies
+ * (`authKitAuth`/`apiKeyAuth`) and the open-mode fallback all attach it to `extra.actor`. Throws when
+ * absent or malformed so a request without a resolvable identity never reaches the tool registry.
+ */
+function actorFromAuthInfo(authInfo) {
+    const actor = authInfo?.extra?.actor;
+    if (!isActor(actor)) {
+        throw new Error('unauthorized: no actor associated with this MCP request');
+    }
+    return actor;
+}
+/** Runtime shape check for the {@link Actor} attached to an MCP `AuthInfo.extra`. */
+function isActor(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    if (typeof candidate.id !== 'string')
+        return false;
+    if (candidate.roles === undefined)
+        return true;
+    return (Array.isArray(candidate.roles) && candidate.roles.every((role) => typeof role === 'string'));
+}
+//# sourceMappingURL=mcp_provider.js.map

package/dist/providers/mcp_provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp_provider.js","sourceRoot":"","sources":["../../providers/mcp_provider.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.18.0";
+export declare const VERSION = "0.19.0";
 export * from './types.js';
 export * from './spi/tool.js';
 export * from './base-tool.js';

package/dist/src/index.js

@@ -1,4 +1,4 @@
-export const VERSION = '0.18.0';
+export const VERSION = '0.19.0';
 export * from './types.js';
 export * from './spi/tool.js';
 export * from './base-tool.js';

package/dist/src/mcp/auth.d.ts

@@ -0,0 +1,90 @@
+import type { ApplicationService } from '@adonisjs/core/types';
+import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+import type { Actor } from '../types.js';
+/**
+ * Runtime context a {@link McpAuthFactory} thunk receives when the MCP provider builds the configured
+ * auth at boot. Carries the booted application so a driver can resolve a peer's service if it needs to.
+ */
+export interface McpAuthContext {
+    app: ApplicationService;
+}
+/**
+ * OAuth metadata the MCP server advertises at `/.well-known/oauth-protected-resource{path}` (RFC 9728)
+ * so an MCP client can discover how to obtain a token. Omitted → the server exposes no OAuth metadata
+ * endpoint and clients must authenticate another way (e.g. a static API key).
+ */
+export interface McpOAuthMetadata {
+    /** The OAuth 2.0 / OIDC authorization server (the authkit issuer, e.g. `http://localhost:3333/oidc`). */
+    issuer: string;
+    /** Authorization endpoint the MCP client redirects to (e.g. `${issuer}/auth`). */
+    authorizationEndpoint: string;
+    /** Token endpoint the MCP client exchanges the code at (e.g. `${issuer}/token`). */
+    tokenEndpoint: string;
+    /** Scopes supported by the authorization server. */
+    scopesSupported: string[];
+    /** Human label for the protected resource. */
+    resourceName: string;
+}
+/**
+ * A configured MCP auth strategy. `verify` validates a bearer token and resolves the acting {@link Actor}
+ * (attached to `AuthInfo.extra.actor`); it MUST throw when the token is missing/invalid/expired. The
+ * same `AuthInfo` is surfaced to the `tools/list` / `tools/call` handlers as `extra.authInfo`, so the
+ * actor the tool registry gates against is exactly the one the auth strategy resolved.
+ */
+export interface McpAuth {
+    /** OAuth metadata to advertise, resolved lazily (the authkit peer may not be bootable until first use). */
+    oauth?: McpOAuthMetadata | (() => McpOAuthMetadata | Promise<McpOAuthMetadata>);
+    /** Validate `token` and resolve the acting actor. Throws `Error` on rejection. */
+    verify(token: string): Promise<AuthInfo>;
+}
+/**
+ * A configured MCP auth strategy, as a lazy thunk the provider calls at boot. Each factory lazily
+ * imports / resolves its peer inside the thunk, so nothing loads until the strategy is actually selected.
+ */
+export type McpAuthFactory = (ctx: McpAuthContext) => McpAuth | Promise<McpAuth>;
+/**
+ * Resolve a `McpAuth` config value (a ready instance or a lazy factory) at provider boot.
+ */
+export declare function resolveMcpAuth(auth: McpAuth | McpAuthFactory, ctx: McpAuthContext): Promise<McpAuth>;
+/** How `authKitAuth()` maps an access token to the MCP actor. Defaults to the account id. */
+export type AuthKitActorResolver = (info: {
+    accountId: string;
+    scopes: string[];
+    clientId: string | undefined;
+}) => Actor | Promise<Actor>;
+/** Options for {@link authKitAuth}. */
+export interface AuthKitMcpAuthOptions {
+    /** Scopes the authorization server advertises. Defaults to the standard authkit scopes. */
+    scopes?: string[];
+    /** Map a validated access token to the acting {@link Actor}. Defaults to `{ id: accountId }`. */
+    toActor?: AuthKitActorResolver;
+    /** Human label for the protected resource. Defaults to `'Agent MCP Server'`. */
+    resourceName?: string;
+}
+/**
+ * Authenticate MCP clients with `@adonis-agora/authkit-server`: verifies the bearer token against the
+ * authkit OIDC provider's stored access tokens (`provider.AccessToken.find`) and advertises OAuth
+ * metadata derived from the issuer so MCP clients can run the full OAuth login flow.
+ *
+ * The authkit peer is resolved lazily — the `verify`/`oauth` accessors touch the container only when
+ * a request actually arrives (by then the app is fully booted and the authkit keystore/encryption
+ * services are ready). `@adonis-agora/authkit-server` stays an optional dependency. Throws a clear
+ * error at first use if the binding isn't resolvable (authkit not installed / provider not registered).
+ */
+export declare function authKitAuth(options?: AuthKitMcpAuthOptions): McpAuthFactory;
+/** Resolve the MCP actor from a validated API key. Defaults to `{ id: apiKey }`. */
+export type ApiKeyActorResolver = (apiKey: string) => Actor | Promise<Actor>;
+/** Options for {@link apiKeyAuth}. */
+export interface ApiKeyMcpAuthOptions {
+    /** Static API keys clients present in `Authorization: Bearer <key>`. */
+    apiKeys: string[];
+    /** Map a validated API key to the acting {@link Actor}. Defaults to `{ id: apiKey }`. */
+    toActor?: ApiKeyActorResolver;
+}
+/**
+ * Authenticate MCP clients with a static list of API keys (no OAuth metadata). Intended for trusted
+ * gateway / machine-to-machine integrations where the host proxies auth and this server just
+ * checks the key. Keys are compared with a constant-time compare to resist timing attacks.
+ */
+export declare function apiKeyAuth(options: ApiKeyMcpAuthOptions): McpAuthFactory;
+//# sourceMappingURL=auth.d.ts.map

package/dist/src/mcp/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/mcp/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gDAAgD,CAAC;AAC/E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,kBAAkB,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yGAAyG;IACzG,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,qBAAqB,EAAE,MAAM,CAAC;IAC9B,oFAAoF;IACpF,aAAa,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,2GAA2G;IAC3G,KAAK,CAAC,EAAE,gBAAgB,GAAG,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAChF,kFAAkF;IAClF,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEjF;;GAEG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,OAAO,GAAG,cAAc,EAC9B,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,OAAO,CAAC,CAKlB;AAuBD,6FAA6F;AAC7F,MAAM,MAAM,oBAAoB,GAAG,CAAC,IAAI,EAAE;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B,KAAK,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;AAE7B,uCAAuC;AACvC,MAAM,WAAW,qBAAqB;IACpC,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,iGAAiG;IACjG,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAgD/E;AAmBD,oFAAoF;AACpF,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;AAE7E,sCAAsC;AACtC,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yFAAyF;IACzF,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,oBAAoB,GAAG,cAAc,CAcxE"}

package/dist/src/mcp/auth.js

@@ -0,0 +1,108 @@
+/**
+ * Resolve a `McpAuth` config value (a ready instance or a lazy factory) at provider boot.
+ */
+export async function resolveMcpAuth(auth, ctx) {
+    if (typeof auth === 'function') {
+        return auth(ctx);
+    }
+    return auth;
+}
+/**
+ * Authenticate MCP clients with `@adonis-agora/authkit-server`: verifies the bearer token against the
+ * authkit OIDC provider's stored access tokens (`provider.AccessToken.find`) and advertises OAuth
+ * metadata derived from the issuer so MCP clients can run the full OAuth login flow.
+ *
+ * The authkit peer is resolved lazily — the `verify`/`oauth` accessors touch the container only when
+ * a request actually arrives (by then the app is fully booted and the authkit keystore/encryption
+ * services are ready). `@adonis-agora/authkit-server` stays an optional dependency. Throws a clear
+ * error at first use if the binding isn't resolvable (authkit not installed / provider not registered).
+ */
+export function authKitAuth(options = {}) {
+    const scopes = options.scopes ?? ['openid', 'profile', 'email', 'offline_access', 'roles'];
+    const toActor = options.toActor ?? (({ accountId }) => ({ id: accountId }));
+    return async ({ app }) => {
+        let servicePromise;
+        const getService = () => {
+            servicePromise ??= resolveAuthKitService(app);
+            return servicePromise;
+        };
+        const oauth = async () => {
+            const service = await getService();
+            const issuer = service.config.issuer;
+            return {
+                issuer,
+                authorizationEndpoint: `${issuer}/auth`,
+                tokenEndpoint: `${issuer}/token`,
+                scopesSupported: scopes,
+                resourceName: options.resourceName ?? 'Agent MCP Server',
+            };
+        };
+        return {
+            oauth,
+            async verify(token) {
+                const service = await getService();
+                const at = await service.provider.AccessToken.find(token);
+                if (!at || at.isExpired) {
+                    throw new Error('invalid or expired access token');
+                }
+                const tokenScopes = (at.scope ?? '').split(' ').filter(Boolean);
+                const actor = await toActor({
+                    accountId: at.accountId,
+                    scopes: tokenScopes,
+                    clientId: at.clientId,
+                });
+                return {
+                    token,
+                    clientId: at.clientId ?? '',
+                    scopes: tokenScopes,
+                    ...(at.exp !== undefined ? { expiresAt: at.exp } : {}),
+                    extra: { actor },
+                };
+            },
+        };
+    };
+}
+/**
+ * Resolve the authkit `OidcService` from the container. `@adonis-agora/authkit-server` augments
+ * `ContainerBindings` with `'authkit.server'`, so `make` is fully typed with no cast.
+ */
+async function resolveAuthKitService(app) {
+    try {
+        return await app.container.make('authkit.server');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`[@adonis-agora/agent] \`authKitAuth()\` could not resolve the authkit server (${message}). Is \`@adonis-agora/authkit-server\` installed and its provider registered in adonisrc.ts?`);
+    }
+}
+/**
+ * Authenticate MCP clients with a static list of API keys (no OAuth metadata). Intended for trusted
+ * gateway / machine-to-machine integrations where the host proxies auth and this server just
+ * checks the key. Keys are compared with a constant-time compare to resist timing attacks.
+ */
+export function apiKeyAuth(options) {
+    const keys = new Set(options.apiKeys);
+    const toActor = options.toActor ?? ((apiKey) => ({ id: apiKey }));
+    return async () => {
+        return {
+            async verify(token) {
+                if (![...keys].some((key) => timingSafeEqual(key, token))) {
+                    throw new Error('invalid API key');
+                }
+                const actor = await toActor(token);
+                return { token, clientId: token, scopes: [], extra: { actor } };
+            },
+        };
+    };
+}
+/** Constant-time string comparison (no `node:crypto` import at module top to keep the browser-safe build). */
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return diff === 0;
+}
+//# sourceMappingURL=auth.js.map

package/dist/src/mcp/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../src/mcp/auth.ts"],"names":[],"mappings":"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"}

package/dist/src/mcp/define_config.d.ts

@@ -0,0 +1,64 @@
+import type { RolesPolicy } from '../spi/roles-policy.js';
+import { apiKeyAuth, authKitAuth } from './auth.js';
+import type { McpAuth, McpAuthFactory } from './auth.js';
+/**
+ * Shape of `config/mcp.ts`. The MCP provider exposes the agent's {@link ToolRegistry} over the Model
+ * Context Protocol (Streamable HTTP): `tools/list` mirrors the tools the acting actor may call
+ * (role-filtered), `tools/call` runs them through the registry (role re-check + schema re-validation).
+ *
+ * ```ts
+ * import { defineMcpConfig, authKitAuth } from '@adonis-agora/agent/mcp'
+ *
+ * export default defineMcpConfig({
+ *   name: 'Lumen Agent',
+ *   version: '1.0.0',
+ *   auth: authKitAuth(),
+ *   path: 'mcp',
+ * })
+ * ```
+ */
+export interface McpConfig {
+    /** Server name reported to MCP clients in the initialize handshake. */
+    name: string;
+    /** Server version reported to MCP clients. */
+    version: string;
+    /**
+     * Route prefix the MCP Streamable HTTP endpoint mounts under. Defaults to `'mcp'` (→ `/mcp`).
+     * OAuth metadata (when `auth.oauth` is set) is served at `/.well-known/oauth-protected-resource{path}`.
+     */
+    path?: string;
+    /**
+     * How MCP clients authenticate. Pass a ready {@link McpAuth} or a lazy {@link McpAuthFactory} thunk
+     * (`authKitAuth()` / `apiKeyAuth()`). Omit → the server is open (no bearer check); the acting actor
+     * falls back to `actor`. Fail-closed: with no `auth` AND no `actor`, requests are rejected.
+     */
+    auth?: McpAuth | McpAuthFactory;
+    /**
+     * The acting actor when `auth` is omitted (dev/open mode). Fail-closed default: omitted → requests
+     * are rejected 401. Set it (e.g. `{ id: 'mcp', roles: ['ADMIN'] }`) to let unauthenticated clients
+     * run tools under that identity.
+     */
+    actor?: {
+        id: string;
+        roles?: string[];
+        tenantRef?: string;
+    };
+    /**
+     * Tool authorization gate. Defaults to `DefaultToolAuthorizer(config.defaultRoles ?? ['ADMIN'])` —
+     * same fail-closed default as the agent provider.
+     */
+    authorizer?: RolesPolicy;
+    /** Roles a tool requires when it declares none. Defaults to `['ADMIN']`. */
+    defaultRoles?: string[];
+    /**
+     * Restrict the exposed tools to this allow-list of names. Omit → all tools the acting actor's roles
+     * permit are exposed.
+     */
+    allowedTools?: string[];
+}
+/** Identity helper giving `config/mcp.ts` full type-checking. */
+export declare function defineMcpConfig(config: McpConfig): McpConfig;
+export { authKitAuth, apiKeyAuth };
+export type { McpAuth, McpAuthFactory, McpAuthContext, McpOAuthMetadata, AuthKitMcpAuthOptions, AuthKitActorResolver, ApiKeyMcpAuthOptions, ApiKeyActorResolver, } from './auth.js';
+export { resolveMcpAuth } from './auth.js';
+//# sourceMappingURL=define_config.d.ts.map

package/dist/src/mcp/define_config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.d.ts","sourceRoot":"","sources":["../../../src/mcp/define_config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;IAChC;;;;OAIG;IACH,KAAK,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D;;;OAGG;IACH,UAAU,CAAC,EAAE,WAAW,CAAC;IACzB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAE5D;AAED,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC;AACnC,YAAY,EACV,OAAO,EACP,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/src/mcp/define_config.js

@@ -0,0 +1,8 @@
+import { apiKeyAuth, authKitAuth } from './auth.js';
+/** Identity helper giving `config/mcp.ts` full type-checking. */
+export function defineMcpConfig(config) {
+    return config;
+}
+export { authKitAuth, apiKeyAuth };
+export { resolveMcpAuth } from './auth.js';
+//# sourceMappingURL=define_config.js.map

package/dist/src/mcp/define_config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.js","sourceRoot":"","sources":["../../../src/mcp/define_config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAuDpD,iEAAiE;AACjE,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC/C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC;AAWnC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/src/mcp/index.d.ts

@@ -0,0 +1,7 @@
+export { defineMcpConfig } from './define_config.js';
+export { authKitAuth, apiKeyAuth, resolveMcpAuth } from './auth.js';
+export { createMcpServer } from './server.js';
+export type { McpConfig } from './define_config.js';
+export type { McpAuth, McpAuthFactory, McpAuthContext, McpOAuthMetadata, AuthKitMcpAuthOptions, AuthKitActorResolver, ApiKeyMcpAuthOptions, ApiKeyActorResolver, } from './auth.js';
+export type { CreateMcpServerOptions, McpToolContextOptions } from './server.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,YAAY,EACV,OAAO,EACP,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC"}

package/dist/src/mcp/index.js

@@ -0,0 +1,4 @@
+export { defineMcpConfig } from './define_config.js';
+export { authKitAuth, apiKeyAuth, resolveMcpAuth } from './auth.js';
+export { createMcpServer } from './server.js';
+//# sourceMappingURL=index.js.map

package/dist/src/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/src/mcp/server.d.ts

@@ -0,0 +1,47 @@
+import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { RolesPolicy } from '../spi/roles-policy.js';
+import { ToolRegistry } from '../tool-registry.js';
+import type { Actor } from '../types.js';
+/**
+ * Runtime context a MCP handler synthesizes for {@link ToolRegistry.invoke}: the acting {@link Actor}
+ * comes from the verified auth, and the run/request ids from the MCP request so tool traces map back
+ * to the MCP session.
+ */
+export interface McpToolContextOptions {
+    /** How the actor is resolved from the transport's verified auth info. */
+    actorFromAuth: (authInfo: AuthInfo | undefined) => Actor;
+    /** How run/thread/request ids are derived. Defaults to the MCP session + request ids. */
+    idsFromRequest?: (sessionId: string | undefined, requestId: string | number | undefined) => {
+        threadId: string;
+        runId: string;
+        requestId: string;
+    };
+}
+/** Options for {@link createMcpServer}. */
+export interface CreateMcpServerOptions extends McpToolContextOptions {
+    /** Server name reported in the initialize handshake. */
+    name: string;
+    /** Server version reported in the initialize handshake. */
+    version: string;
+    /** The agent tool registry to expose. */
+    registry: ToolRegistry;
+    /** Tool authorization gate (role re-check happens per call, defense-in-depth). */
+    policy: RolesPolicy;
+    /** Optional allow-list restricting which tools are exposed. */
+    allowedTools?: string[];
+}
+/**
+ * Build a low-level MCP `Server` that exposes the agent's {@link ToolRegistry} over the wire:
+ *
+ * - `tools/list` → `registry.definitionsFor(actor, policy, allowedTools)` — the tools the acting
+ *   actor's roles permit (fail-closed via the same `RolesPolicy` the agent loop uses), converted to
+ *   MCP `Tool` descriptors with JSON-Schema inputs.
+ * - `tools/call` → `registry.invoke(name, args, ctx, policy)` — role re-check + input re-validation
+ *   before the handler runs (the registry's own defense-in-depth), so a stale tool list can never
+ *   bypass the gate.
+ *
+ * Use this in the MCP provider (one server per session, connected to that session's transport).
+ */
+export declare function createMcpServer(options: CreateMcpServerOptions): Server;
+//# sourceMappingURL=server.d.ts.map

package/dist/src/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/mcp/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gDAAgD,CAAC;AAC/E,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAKnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,yEAAyE;IACzE,aAAa,EAAE,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,KAAK,KAAK,CAAC;IACzD,yFAAyF;IACzF,cAAc,CAAC,EAAE,CACf,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,KACnC;QACH,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,2CAA2C;AAC3C,MAAM,WAAW,sBAAuB,SAAQ,qBAAqB;IACnE,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,QAAQ,EAAE,YAAY,CAAC;IACvB,kFAAkF;IAClF,MAAM,EAAE,WAAW,CAAC;IACpB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AA4CD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAgDvE"}

package/dist/src/mcp/server.js

@@ -0,0 +1,94 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { toJsonSchemaCompat } from '@modelcontextprotocol/sdk/server/zod-json-schema-compat.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * True for a Zod schema (tags its Standard Schema props with `vendor: 'zod'`). Narrows to the SDK's
+ * `AnyObjectSchema` so `toJsonSchemaCompat` can consume it without a cast.
+ */
+function isZodSchema(schema) {
+    return schema['~standard'].vendor === 'zod';
+}
+/** True when the schema carries the Standard JSON Schema converter (`~standard.jsonSchema.input`). */
+function hasStandardJsonSchema(schema) {
+    const standard = schema['~standard'];
+    if (!('jsonSchema' in standard)) {
+        return false;
+    }
+    const converter = standard.jsonSchema;
+    return (typeof converter === 'object' &&
+        converter !== null &&
+        'input' in converter &&
+        typeof converter.input === 'function');
+}
+/**
+ * Convert a core `StandardSchemaV1` tool schema into the JSON Schema MCP clients see in `tools/list`.
+ * Zod schemas are converted with the SDK's compat helper (handles both v3 and v4); schemas that expose
+ * the Standard JSON Schema extension (Valibot/ArkType/Zod 4) hand their `input()` schema straight
+ * through. Anything else degrades to a permissive object schema — the loop still validates the real
+ * schema on call via `~standard.validate`.
+ */
+function toJsonSchema(schema) {
+    if (isZodSchema(schema)) {
+        return toJsonSchemaCompat(schema);
+    }
+    if (hasStandardJsonSchema(schema)) {
+        return schema['~standard'].jsonSchema.input();
+    }
+    return { type: 'object', properties: {}, additionalProperties: true };
+}
+/**
+ * Build a low-level MCP `Server` that exposes the agent's {@link ToolRegistry} over the wire:
+ *
+ * - `tools/list` → `registry.definitionsFor(actor, policy, allowedTools)` — the tools the acting
+ *   actor's roles permit (fail-closed via the same `RolesPolicy` the agent loop uses), converted to
+ *   MCP `Tool` descriptors with JSON-Schema inputs.
+ * - `tools/call` → `registry.invoke(name, args, ctx, policy)` — role re-check + input re-validation
+ *   before the handler runs (the registry's own defense-in-depth), so a stale tool list can never
+ *   bypass the gate.
+ *
+ * Use this in the MCP provider (one server per session, connected to that session's transport).
+ */
+export function createMcpServer(options) {
+    const { registry, policy, allowedTools, actorFromAuth, idsFromRequest } = options;
+    const server = new Server({ name: options.name, version: options.version }, { capabilities: { tools: {} } });
+    const buildCtx = (authInfo, sessionId) => {
+        const actor = actorFromAuth(authInfo);
+        const ids = idsFromRequest
+            ? idsFromRequest(sessionId, undefined)
+            : {
+                threadId: `mcp:${sessionId ?? actor.id}`,
+                runId: `mcp:${sessionId ?? 'run'}`,
+                requestId: `mcp:${sessionId ?? 'req'}`,
+            };
+        return { actor, ...ids };
+    };
+    server.setRequestHandler(ListToolsRequestSchema, async (request, extra) => {
+        const actor = actorFromAuth(extra.authInfo);
+        const defs = await registry.definitionsFor(actor, policy, allowedTools);
+        return {
+            tools: defs.map((definition) => ({
+                name: definition.name,
+                description: definition.description,
+                inputSchema: toJsonSchema(definition.inputSchema),
+            })),
+        };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const ctx = buildCtx(extra.authInfo, extra.sessionId);
+        const { name, arguments: args } = request.params;
+        try {
+            const output = await registry.invoke(name, args ?? {}, ctx, policy);
+            return {
+                content: [
+                    { type: 'text', text: typeof output === 'string' ? output : JSON.stringify(output) },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: message }], isError: true };
+        }
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/src/mcp/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/mcp/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAEnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,4DAA4D,CAAC;AAChG,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAwCnG;;;GAGG;AACH,SAAS,WAAW,CAAC,MAAwB;IAC3C,OAAO,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,KAAK,KAAK,CAAC;AAC9C,CAAC;AAED,sGAAsG;AACtG,SAAS,qBAAqB,CAAC,MAAwB;IAGrD,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;IACrC,IAAI,CAAC,CAAC,YAAY,IAAI,QAAQ,CAAC,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,SAAS,GAAG,QAAQ,CAAC,UAAU,CAAC;IACtC,OAAO,CACL,OAAO,SAAS,KAAK,QAAQ;QAC7B,SAAS,KAAK,IAAI;QAClB,OAAO,IAAI,SAAS;QACpB,OAAO,SAAS,CAAC,KAAK,KAAK,UAAU,CACtC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAS,YAAY,CAAC,MAAwB;IAC5C,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IACD,IAAI,qBAAqB,CAAC,MAAM,CAAC,EAAE,CAAC;QAClC,OAAO,MAAM,CAAC,WAAW,CAAC,CAAC,UAAU,CAAC,KAAK,EAA6B,CAAC;IAC3E,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE,oBAAoB,EAAE,IAAI,EAAE,CAAC;AACxE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,OAA+B;IAC7D,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC;IAClF,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,EAChD,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAChC,CAAC;IAEF,MAAM,QAAQ,GAAG,CAAC,QAA8B,EAAE,SAA6B,EAAa,EAAE;QAC5F,MAAM,KAAK,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;QACtC,MAAM,GAAG,GAAG,cAAc;YACxB,CAAC,CAAC,cAAc,CAAC,SAAS,EAAE,SAAS,CAAC;YACtC,CAAC,CAAC;gBACE,QAAQ,EAAE,OAAO,SAAS,IAAI,KAAK,CAAC,EAAE,EAAE;gBACxC,KAAK,EAAE,OAAO,SAAS,IAAI,KAAK,EAAE;gBAClC,SAAS,EAAE,OAAO,SAAS,IAAI,KAAK,EAAE;aACvC,CAAC;QACN,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,EAAE,CAAC;IAC3B,CAAC,CAAC;IAEF,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE;QACxE,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC5C,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;QACxE,OAAO;YACL,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;gBAC/B,IAAI,EAAE,UAAU,CAAC,IAAI;gBACrB,WAAW,EAAE,UAAU,CAAC,WAAW;gBACnC,WAAW,EAAE,YAAY,CAAC,UAAU,CAAC,WAAW,CAAC;aAClD,CAAC,CAAC;SACJ,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE;QACvE,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;QACtD,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;QACjD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;YACpE,OAAO;gBACL,OAAO,EAAE;oBACP,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE;iBACrF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACvE,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/stubs/config/mcp.stub

@@ -0,0 +1,42 @@
+{{{
+  exports({ to: app.configPath('mcp.ts') })
+}}}
+import { defineMcpConfig, authKitAuth } from '@adonis-agora/agent/mcp'
+// import { apiKeyAuth } from '@adonis-agora/agent/mcp'
+
+/**
+ * Configuration for the MCP (Model Context Protocol) endpoint. The provider exposes the agent's tool
+ * registry over Streamable HTTP: `tools/list` mirrors the tools the acting actor may call and
+ * `tools/call` runs them through the same role-checked registry the agent loop uses.
+ *
+ * Requires `@adonis-agora/agent`'s agent provider (which owns the ToolRegistry singleton) to be
+ * registered. Register the MCP provider in adonisrc.ts:
+ *
+ *   providers: [
+ *     ...existing,
+ *     () => import('@adonis-agora/agent/mcp_provider'),
+ *   ]
+ *
+ * The endpoint mounts at `/mcp`. When `auth` exposes OAuth metadata (authKitAuth), MCP clients discover
+ * the login flow at `/.well-known/oauth-protected-resource/mcp`.
+ */
+export default defineMcpConfig({
+  name: 'Agent MCP Server',
+  version: '1.0.0',
+
+  // path: 'mcp',
+
+  // Authenticate MCP clients against @adonis-agora/authkit-server (OAuth OIDC): verifies the bearer
+  // token against the authkit provider and advertises OAuth metadata so clients can log in.
+  auth: authKitAuth(),
+
+  // Or static API keys for trusted gateway integrations (no OAuth metadata):
+  // auth: apiKeyAuth({ apiKeys: ['mcp_xxx'] }),
+
+  // Open/dev mode — run every request under a fixed identity. Fail-closed: omit this (and auth) and
+  // requests are rejected 401.
+  // actor: { id: 'mcp', roles: ['ADMIN'] },
+
+  // Restrict the exposed tools to an allow-list by name.
+  // allowedTools: ['calcular_estatisticas', 'estatistica_inferencial'],
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/agent",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {
@@ -23,6 +23,16 @@
       "import": "./dist/src/ai-sdk/index.js",
       "default": "./dist/src/ai-sdk/index.js"
     },
+    "./mcp": {
+      "types": "./dist/src/mcp/index.d.ts",
+      "import": "./dist/src/mcp/index.js",
+      "default": "./dist/src/mcp/index.js"
+    },
+    "./mcp_provider": {
+      "types": "./dist/providers/mcp_provider.d.ts",
+      "import": "./dist/providers/mcp_provider.js",
+      "default": "./dist/providers/mcp_provider.js"
+    },
     "./testing": {
       "types": "./dist/src/testing/index.d.ts",
       "import": "./dist/src/testing/index.js",
@@ -96,6 +106,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@standard-schema/spec": "^1.0.0"
   },
   "peerDependencies": {
@@ -193,7 +204,7 @@
     "build": "pnpm run clean && tsc -p tsconfig.build.json && pnpm run copy:stubs && pnpm run check:dist",
     "check:dist": "node ../../scripts/assert-build-output.mjs dist src/index.js",
     "clean": "rm -rf dist",
-    "copy:stubs": "mkdir -p dist/stubs/config dist/stubs/database/migrations && cp stubs/config/agent.stub dist/stubs/config/agent.stub && cp -r stubs/database/migrations/. dist/stubs/database/migrations/",
+    "copy:stubs": "mkdir -p dist/stubs/config dist/stubs/database/migrations && cp stubs/config/agent.stub dist/stubs/config/agent.stub && cp stubs/config/mcp.stub dist/stubs/config/mcp.stub && cp -r stubs/database/migrations/. dist/stubs/database/migrations/",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.tests.json"