apcore-mcp

Automatic MCP Server & OpenAI Tools Bridge for apcore.

Converts apcore module registries into Model Context Protocol (MCP) tool definitions and OpenAI-compatible function calling formats — zero boilerplate required.

Features

• MCP Server — Expose apcore modules as MCP tools over stdio, Streamable HTTP, or SSE

• OpenAI Tools — Convert modules to OpenAI function calling format with strict mode support

• Markdown tool descriptions (richDescription: true, v0.15+) — render Tool.description and OpenAI function.description as canonical apcore-toolkit Markdown so LLMs get more decision-relevant signal per token. Requires apcore-toolkit (declared as optionalDependencies) and await MCPServerFactory.prepare() at startup.

• Module preview meta-tool (__apcore_module_preview, v0.15+) — drives executor.validate() to predict state changes WITHOUT executing the module (apcore PROTOCOL_SPEC §5.6). Returns {valid, requires_approval, predicted_changes, checks} so AI orchestrators can ask "what would change?" before invoking.

• Schema Conversion — Inline $defs/$ref from Pydantic-generated JSON Schema

• Annotation Mapping — Map module annotations to MCP hints and OpenAI description suffixes

• Approval Mechanism — Built-in elicitation-based approval flow for sensitive tool executions

• Error Mapping — Sanitize internal errors for safe client-facing responses

• Dynamic Registration — Listen for registry changes and update tools at runtime

• Tool Explorer — Browser-based UI for browsing schemas and testing tools interactively

• CLI — Launch an MCP server from the command line

• Config Bus integration — Registers an mcp namespace with the apcore Config Bus; configure via unified apcore.yaml or APCORE_MCP_* env vars

• Error Formatter Registry — Registers an MCP-specific error formatter for ecosystem-wide consistent error handling

Documentation

For full documentation, including Quick Start guides for both Python and TypeScript, visit: https://aiperceivable.github.io/apcore-mcp/

Requirements

• Node.js >= 18.0.0

• apcore-js >= 0.21.1

• Optional: apcore-toolkit >= 0.6.1 for Markdown-rendered tool descriptions (declared under optionalDependencies).

Installation

npm install apcore-mcp

apcore-js is included as a direct dependency — no separate install needed.

Quick Start

Programmatic API

import { serve, toOpenaiTools } from "apcore-mcp";

// Launch MCP server over stdio
await serve(executor);

// Launch over Streamable HTTP
await serve(executor, {
  transport: "streamable-http",
  host: "127.0.0.1",
  port: 8000,
});

// Export OpenAI tool definitions
const tools = toOpenaiTools(registry, {
  embedAnnotations: true,
  strict: true,
});

CLI

# stdio (default)
npx apcore-mcp --extensions-dir ./extensions

# Streamable HTTP
npx apcore-mcp --extensions-dir ./extensions --transport streamable-http --port 8000

# SSE
npx apcore-mcp --extensions-dir ./extensions --transport sse --port 8000

CLI Arguments

JWT key resolution priority: --jwt-key-file > --jwt-secret > APCORE_JWT_SECRET environment variable.

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "apcore": {
      "command": "npx",
      "args": ["apcore-mcp", "--extensions-dir", "/path/to/your/extensions"]
    }
  }
}

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "apcore": {
      "command": "npx",
      "args": ["apcore-mcp", "--extensions-dir", "./extensions"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "apcore": {
      "command": "npx",
      "args": ["apcore-mcp", "--extensions-dir", "./extensions"]
    }
  }
}

Remote HTTP access

npx apcore-mcp --extensions-dir ./extensions \
    --transport streamable-http \
    --host 0.0.0.0 \
    --port 9000

Connect any MCP client to http://your-host:9000/mcp.

API Reference

Programmatic API – APCoreMCP class

The APCoreMCP class is the recommended OOP entry point. It bundles a unified configuration object, lazy backend resolution (path / Registry / Executor), and exposes serve / asyncServe / toOpenaiTools as instance methods so you configure once and use everywhere.

import { APCoreMCP } from "apcore-mcp";

// 1. Point at an extensions directory (lazy discovery on first use)
const mcp = new APCoreMCP("./extensions", {
  name: "my-server",
  tags: ["public"],
  observability: true,
});

// 2. Launch as MCP server (blocks until shutdown)
await mcp.serve({ transport: "streamable-http", port: 8000, explorer: true });

// 3. Or export OpenAI tool definitions
const tools = mcp.toOpenaiTools({ strict: true });

// 4. Or embed into an existing HTTP server
const app = await mcp.asyncServe({ explorer: true });
// app.handler is a Node.js request handler; call app.close() on shutdown

// 5. Or pass an existing Registry / Executor
import { Registry } from "apcore-js";
const registry = new Registry({ extensionsDir: "./extensions" });
await registry.discover();
const mcp2 = new APCoreMCP(registry, { name: "my-server", tags: ["public"] });

Constructor

new APCoreMCP(
  extensionsDirOrBackend: string | Registry | Executor,
  options?: APCoreMCPOptions,
);

The first argument is either a path to an apcore extensions directory (discovery is deferred to first use) or an existing Registry / Executor instance.

APCoreMCPOptions fields

• name — MCP server name. Default: "apcore-mcp"

• version — MCP server version. Default: package version

• tags — Filter modules by tag list

• prefix — Filter modules by ID prefix

• logLevel — Minimum log level (DEBUG | INFO | WARNING | ERROR | CRITICAL)

• validateInputs — Validate inputs against schemas. Default: false

• metricsCollector — MetricsExporter or true to auto-instantiate

• observability — Enable the full metrics + usage observability stack

• async — boolean | { enabled?, maxConcurrent?, maxTasks? } for the Async Task Bridge (F-043)

• authenticator — Optional Authenticator (HTTP transports only)

• requireAuth — If true (default), reject unauthenticated requests with 401

• exemptPaths — Paths exempt from authentication

• approvalHandler — Optional approval handler passed to the Executor

• outputFormatter — Custom function to format tool execution results

• middleware — Array of apcore Middleware installed via executor.use()

• acl — Optional apcore ACL instance installed via executor.setAcl()

Properties

• .registry — The underlying apcore Registry (resolved on first access)

• .executor — The underlying apcore Executor (populated after serve() / asyncServe())

• .tools — List of discovered module IDs that will be exposed as tools (honours tags / prefix)

Methods

• .serve(options?) — Launch an MCP server. Accepts APCoreMCPServeOptions: transport, host, port, onStartup, onShutdown, explorer, explorerPrefix, allowExecute, explorerTitle, explorerProjectName, explorerProjectUrl. Constructor-level options (auth, observability, middleware, acl, async, etc.) are applied automatically.

• .asyncServe(options?) — Build an embeddable Node.js HTTP request handler. Accepts APCoreMCPAsyncServeOptions: explorer, explorerPrefix, allowExecute, explorerTitle, explorerProjectName, explorerProjectUrl, endpoint. Returns { handler, close }.

• .toOpenaiTools(options?) — Export modules as OpenAI-compatible tool definitions. Accepts ToOpenaiToolsOptions: embedAnnotations, strict. tags / prefix are inherited from the constructor.

serve(registryOrExecutor, options?)

Launch an MCP Server that exposes all apcore modules as tools.

function serve(
  registryOrExecutor: Registry | Executor,
  options?: {
    // Transport
    transport?: "stdio" | "streamable-http" | "sse";
    host?: string;
    port?: number;
    // Identity
    name?: string;
    version?: string;
    // Lifecycle
    onStartup?: () => void | Promise<void>;
    onShutdown?: () => void | Promise<void>;
    // Module filtering / discovery
    tags?: string[] | null;
    prefix?: string | null;
    dynamic?: boolean;
    validateInputs?: boolean;
    logLevel?: "DEBUG" | "INFO" | "WARNING" | "ERROR" | "CRITICAL";
    // Async Task Bridge (F-043)
    async?: boolean | { enabled?: boolean; maxConcurrent?: number; maxTasks?: number };
    // Executor wiring
    middleware?: unknown[];
    acl?: unknown;
    approvalHandler?: unknown;
    strategy?: string;
    // Observability (F-044)
    metricsCollector?: MetricsExporter | boolean;
    observability?: ObservabilityFlag;
    trace?: boolean;
    // Output handling
    outputFormatter?: (result: Record<string, unknown>) => string;
    redactOutput?: boolean;
    // Auth (HTTP transports only)
    authenticator?: Authenticator;
    requireAuth?: boolean;
    exemptPaths?: string[];
    // Tool Explorer UI
    explorer?: boolean;
    explorerPrefix?: string;
    allowExecute?: boolean;
    explorerTitle?: string;
    explorerProjectName?: string;
    explorerProjectUrl?: string;
    // Adapter overrides (advanced — Extension Bridge)
    schemaConverter?: SchemaConverter;
    annotationMapper?: AnnotationMapper;
    errorMapper?: ErrorMapper;
  }
): Promise<void>;

Options reference:

Transport

• transport — "stdio" (default), "streamable-http", or "sse"

• host — Host address for HTTP-based transports. Default: "127.0.0.1"

• port — Port for HTTP-based transports. Default: 8000

Identity

• name — MCP server name. Default: "apcore-mcp"

• version — MCP server version. Default: package version

Lifecycle

• onStartup — Async callback invoked before the server starts

• onShutdown — Async callback invoked after the server stops (or on error)

Module filtering / discovery

• tags — Filter modules by tag list. Default: null (no filtering)

• prefix — Filter modules by ID prefix. Default: null (no filtering)

• dynamic — Enable dynamic tool registration via RegistryListener. Default: false

• validateInputs — Validate inputs against schemas before dispatch. Default: false

• logLevel — Minimum log level. Suppresses console methods below this level

Async Task Bridge (F-043)

• async — Enable the AsyncTaskBridge and __apcore_task_* meta-tools. Pass false to disable, or { maxConcurrent, maxTasks } for fine-grained tuning. Default: true

Executor wiring

• middleware — Array of apcore Middleware instances installed via executor.use(). Appended to any middleware declared under Config Bus key mcp.middleware

• acl — Optional apcore ACL instance installed via executor.setAcl(). Caller-supplied ACL takes precedence over mcp.acl Config Bus entry

• approvalHandler — Optional approval handler passed to the Executor (e.g. ElicitationApprovalHandler)

• strategy — Execution strategy name passed to the Executor (e.g. "standard", "internal")

Observability (F-044)

• metricsCollector — MetricsExporter instance, or true to auto-instantiate apcore-js's MetricsCollector and install MetricsMiddleware

• observability — Enable the full observability stack (metrics + usage middleware) and expose /metrics + /usage endpoints

• trace — When true, enables pipeline trace via callWithTrace(). Adds _meta.trace to non-streaming tool responses. Default: false

Output handling

• outputFormatter — Custom function to format tool execution results. When undefined, results are serialized with JSON.stringify(result)

• redactOutput — When true (default), redact sensitive fields from tool output via apcore's redactSensitive() before formatting

Auth (HTTP transports only)

• authenticator — Authenticator instance for request authentication

• requireAuth — If true (default), unauthenticated requests are rejected with 401. Set to false for permissive mode

• exemptPaths — Paths exempt from authentication. Default: ["/health", "/metrics"]

Tool Explorer UI

• explorer — Enable the browser-based Tool Explorer UI (HTTP only). Default: false

• explorerPrefix — URL prefix for the explorer. Default: "/explorer"

• allowExecute — Allow tool execution from the explorer UI. Default: false

• explorerTitle — Custom title for the Tool Explorer UI page

• explorerProjectName — Project name shown in the explorer UI footer

• explorerProjectUrl — Project URL shown in the explorer UI footer

Adapter overrides (advanced — Extension Bridge, F-042)

• schemaConverter — Override the default SchemaConverter (custom JSON Schema strictness/dialect)

• annotationMapper — Override the default AnnotationMapper (custom annotation wire format)

• errorMapper — Override the default ErrorMapper consumed by ExecutionRouter

asyncServe(registryOrExecutor, options?)

Embed the MCP server into a larger Node.js HTTP application. Returns an HTTP request handler and a close function for lifecycle management.

import { asyncServe } from "apcore-mcp";

const { handler, close } = await asyncServe(executor, {
  name: "apcore-mcp",
  explorer: true,
  allowExecute: true,
});

// Mount in a custom HTTP server
const server = http.createServer(handler);
server.listen(8000);

// Clean up when done
await close();

Accepts the same options as serve() except transport, host, port, onStartup, and onShutdown.

Output Formatting

By default, tool execution results are serialized as JSON (JSON.stringify). You can customize this by passing an outputFormat name or a custom outputFormatter function.

Built-in formats (requires apcore-toolkit 0.7.0+):

// Via CLI
// npx apcore-mcp --extensions-dir ./extensions --output-format csv

// Via API
const mcp = new APCoreMCP("./extensions", { outputFormat: "csv" });

Supports json, csv, and jsonl. Non-tabular data gracefully falls back to JSON.

Tool Explorer

When explorer: true is passed to serve(), a browser-based Tool Explorer UI is mounted on HTTP transports. It provides an interactive page for browsing tool schemas and testing tool execution.

await serve(registry, {
  transport: "streamable-http",
  explorer: true,
  allowExecute: true,
});
// Open http://127.0.0.1:8000/explorer/ in a browser

Endpoints:

• HTTP transports only (streamable-http, sse). Silently ignored for stdio.

• Execution disabled by default — set allowExecute: true to enable Try-it.

• Custom prefix — use explorerPrefix: "/browse" to mount at a different path.

• Authorization UI — Swagger-UI-style Authorization input field. Paste a Bearer token to authenticate tool execution requests. Generated cURL commands automatically include the Authorization header.

JWT Authentication

apcore-mcp supports JWT Bearer token authentication for HTTP-based transports.

Programmatic Usage

import { serve, JWTAuthenticator } from "apcore-mcp";

const authenticator = new JWTAuthenticator({
  key: "your-secret-key",
  algorithms: ["HS256"],
  audience: "my-app",
  issuer: "auth-service",
  // Map custom claims to Identity fields
  claimMapping: {
    id: "sub",
    type: "type",
    roles: "roles",
    attrs: ["email", "org"],  // Extra claims → Identity.attrs
  },
  // Claims that must be present in the token (default: ["sub"])
  requireClaims: ["sub", "email"],
  // Set to false for permissive mode (allow unauthenticated requests)
  requireAuth: true,
});

await serve(executor, {
  transport: "streamable-http",
  authenticator,
  // Custom exempt paths (default: ["/health", "/metrics"])
  exemptPaths: ["/health", "/metrics", "/status"],
});

CLI Flags

JWT key resolution priority: --jwt-key-file > --jwt-secret > APCORE_JWT_SECRET environment variable.

curl Examples

# Authenticated request
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-jwt-token>" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Health check (always exempt)
curl http://localhost:8000/health

Per-request identity helpers

When auth is enabled, each request runs inside an AsyncLocalStorage context whose value is the verified Identity. Modules and middleware read it with getCurrentIdentity() — no need to thread it through every function.

import { getCurrentIdentity, identityStorage } from "apcore-mcp";
import type { Identity } from "apcore-mcp";

// Inside a module / middleware called from a tool invocation:
const id: Identity | null = getCurrentIdentity();
if (id) {
  // id.id (user id), id.type ("user" | "service" | ...), id.roles, id.attrs
}

// Lower-level access (e.g. for running custom code inside a known identity):
identityStorage.run(myIdentity, async () => {
  /* code that calls getCurrentIdentity() */
});

Python parity: apcore_mcp.get_current_identity() / auth_identity_var. Rust parity: apcore_mcp::AUTH_IDENTITY task-local.

Mounting the Explorer behind your own server

If you embed the bridge via asyncServe(...) instead of serve(...), gate the explorer routes behind an auth hook with buildExplorerAuthHook(authenticator):

import { buildExplorerAuthHook } from "apcore-mcp";
import { JWTAuthenticator } from "apcore-mcp";

const auth = new JWTAuthenticator({ key: process.env.JWT_SECRET! });
const guard = buildExplorerAuthHook(auth);

// `guard` is a `(req, next) => Promise<Response>` hook accepted by
// mcp-embedded-ui's Hono router. Returns a 401 response when the
// Authorization header is missing or invalid; otherwise runs `next()`
// inside `identityStorage.run(identity, ...)` so the explorer's
// downstream handlers see the authenticated identity.

Custom observability stack (advanced)

For callers who don't want the serve(... observability: true) shorthand, installObservability wires the metrics + usage middleware onto an existing Executor directly. It is what serve() calls internally.

import { installObservability } from "apcore-mcp";
import type { ObservabilityFlag } from "apcore-mcp";

const stack = await installObservability(executor, /* metricsCollector */ null, true satisfies ObservabilityFlag);
// stack.metricsCollector / stack.usageCollector are then exposed on
// the `/metrics` and `/usage` endpoints by your own HTTP wiring.

toOpenaiTools(registryOrExecutor, options?)

Export apcore modules as OpenAI-compatible tool definitions.

function toOpenaiTools(
  registryOrExecutor: Registry | Executor,
  options?: {
    embedAnnotations?: boolean;
    strict?: boolean;
    tags?: string[];
    prefix?: string;
  }
): OpenAIToolDef[];

Options:

• embedAnnotations — Append annotation metadata to tool descriptions (default: false)

• strict — Enable OpenAI strict mode: adds additionalProperties: false, makes all properties required, wraps optional properties with nullable (default: false)

• tags — Filter modules by tags

• prefix — Filter modules by ID prefix

reportProgress(context, progress, total?, message?)

Report execution progress to the MCP client. No-ops silently when called outside an MCP context (no callback injected).

import { reportProgress } from "apcore-mcp";

// Inside a module's execute() method:
await reportProgress(context, 5, 10, "Processing item 5 of 10");

Parameters:

• context — Object with a data dict (apcore Context or BridgeContext)

• progress — Current progress value

• total — Optional total for percentage calculation

• message — Optional human-readable progress message

elicit(context, message, requestedSchema?)

Ask the MCP client for user input via the elicitation protocol. Returns null when called outside an MCP context.

import { elicit } from "apcore-mcp";
import type { ElicitResult } from "apcore-mcp";

// Inside a module's execute() method:
const result: ElicitResult | null = await elicit(
  context,
  "Are you sure you want to proceed?",
  {
    type: "object",
    properties: {
      confirmed: { type: "boolean", description: "Confirm action" },
    },
    required: ["confirmed"],
  },
);

if (result?.action === "accept") {
  // User confirmed
}

Parameters:

• context — Object with a data dict (apcore Context or BridgeContext)

• message — Message to display to the user

• requestedSchema — Optional JSON Schema describing the expected input

Returns: ElicitResult with action ("accept", "decline", or "cancel") and optional content, or null if not in an MCP context.

Config Bus Integration

apcore-mcp registers an mcp namespace with the apcore Config Bus when serve() or asyncServe() is called. MCP settings can live alongside other apcore configuration in a single apcore.yaml:

apcore:
  version: "1.0.0"
mcp:
  transport: streamable-http
  host: 0.0.0.0
  port: 9000
  explorer: true
  require_auth: false

Environment variable overrides use the APCORE_MCP_ prefix:

APCORE_MCP_TRANSPORT=streamable-http
APCORE_MCP_PORT=9000
APCORE_MCP_EXPLORER=true

Defaults: transport=stdio, host=127.0.0.1, port=8000, explorer=false, require_auth=true.

The namespace, prefix, and defaults are also available as importable constants:

import { MCP_NAMESPACE, MCP_ENV_PREFIX, MCP_DEFAULTS, registerMcpNamespace } from "apcore-mcp";

Development

# Install dependencies
npm install

# Type check
npm run typecheck

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build
npm run build

# Watch mode
npm run dev

License

Apache-2.0