Dynamic Tool discovery

[0xKoller]

Tools are no longer unconditionally registered, server operators and tool authors can now control which tools are visible based on authentication, scopes, dependencies, and configuration.

How it works

Three filtering layers, evaluated in order:

1. Build-time: tools.include / tools.exclude in xmcp.config.ts controls which tools get bundled. Excluded tools never load.
2. Runtime per-tool filters: New optional ToolMetadata fields:

• enabled: false: disabled by default (overridable by config include/enable)
• requiresAuth: true: hidden from unauthenticated clients
• requiredScopes: ['admin']: requires all listed OAuth scopes

3. Dependency resolution: dependsOn: ['other-tool'] makes a tool visible only when its dependencies pass their own filters. Resolved iteratively with circular dependency detection.

Hidden tools return "tool not found" if called directly. their existence is never revealed.

Config example

  // xmcp.config.ts
  export default {
    http: true,
    tools: {
      exclude: ['debug-tool'],        // never bundle this
      enable: ['experimental'],       // override enabled: false
    },
  }

Tool metadata example

  export const metadata: ToolMetadata = {
    name: 'advanced-analytics',
    description: 'Analytics dashboard',
    requiresAuth: true,
    requiredScopes: ['admin'],
    dependsOn: ['data-source'],      // only visible when data-source is registered
  }

Related Issues

Resolves XMCP-150

[linear]

XMCP-150 Dynamic Tool discovery

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
xmcp-website	Ready	Preview, Comment	Apr 3, 2026 8:00pm

[github-actions]

Rspack Bundle Analysis

Build	Assets	Total Size (MB)	Build Time
Main Compiler	4	6.34	5.10s
Runtime Compiler	6	5.37	5.64s

Main Compiler

Source: stats-main.json

Asset	Chunk	Size (KB)	Size (MB)
cli.js	cli	6021.97	5.88
index.js	index	368.80	0.36
cloudflare.js	cloudflare	81.70	0.08
detached-flush.js	detached-flush	15.18	0.01

Total emitted JS: 6.34 MB

Runtime Compiler

Source: stats-runtime.json

Asset	Chunk	Size (KB)	Size (MB)
http.js	http	1307.98	1.28
adapter-nestjs.js	adapter-nestjs	1284.25	1.25
adapter-nextjs.js	adapter-nextjs	1278.32	1.25
adapter-express.js	adapter-express	1276.56	1.25
stdio.js	stdio	345.42	0.34
headers.js	headers	1.33	0.00

Total emitted JS: 5.37 MB

Package Footprint (npm pack + npm install)

Item	Size (KB)	Size (MB)
Tarball (.tgz)	4637.04	4.53
dist/	12054.08	11.77
node_modules/	101291.02	98.92
dist + node_modules	113345.11	110.69

[0xKoller]

@greptileai re review