Progressive Disclosure for Typed Library Discovery & Introspection in MCP

[harche]

Pre-submission Checklist

• I have verified this would not be more appropriate as a feature request in a specific repository
• I have searched existing discussions to avoid duplicates

Your Idea

Progressive Disclosure for Typed Library Discovery & Introspection in MCP

I've been experimenting with an MCP server called ProDisco, which exposes the official Kubernetes TypeScript client through a progressive disclosure pattern inspired by Anthropic’s guidance on code-execution MCP servers.

Instead of registering hundreds of narrowly scoped tools like listPods, createDeployment, etc., the server exposes just a couple of generic tools:

• A search tool (e.g. kubernetes.searchTools) that lets the model discover relevant operations from the Kubernetes TypeScript client using structured parameters (e.g. resourceType, action, scope, risk level).
• A type discovery tool (e.g. kubernetes.getTypeDefinitions) that returns machine-readable input/output type information (derived from the TypeScript client’s types) for those operations.

The model then uses this information to write its own TypeScript that imports and composes the underlying client library, with only the final console output returned to the chat. This seems like a reusable pattern for any typed SDK (GitHub, Salesforce, GCP, Stripe, etc.), not just Kubernetes.

What I’d like to explore is whether this should be elevated from an implementation pattern to an optional, protocol-level capability in MCP itself: i.e., a standard way for servers to expose “library-backed, typed operation discovery” that clients can rely on, rather than each server inventing its own ad-hoc schema. I’m imagining this as a candidate for a Standards Track SEP, along the lines described in the SEP guidelines.

---

What problem does this solve?

• Unbounded tool surfaces for rich SDKs
  Rich APIs (Kubernetes, cloud SDKs, CRMs, etc.) can easily balloon into hundreds of MCP tools if every operation is exposed directly. That’s hard to maintain, hard to permission, and hard for models to navigate.

• Lack of a consistent way to “browse” a library
  Today, each server invents its own ad-hoc way to expose a library: some register dozens of concrete tools, some expose raw HTTP endpoints, some don’t expose types at all. Models can’t rely on a consistent pattern to discover “what can I do with this SDK?”

• Poor reuse of existing type information
  Typed SDKs (TypeScript, OpenAPI-generated clients, etc.) already encode rich types, but MCP tools often flatten these into loosely-typed JSON parameters. That wastes information that could make codegen safer and more reliable.

• Token and latency costs from over-exposing data
  Without progressive disclosure, servers either dump huge tool definitions and schemas into the context, or they require many back-and-forth tool calls to gradually discover capabilities. A search + type-discovery pattern reduces both the amount of schema shipped and the number of tool calls.

---

Who would benefit from this?

• MCP server authors wrapping existing SDKs
  Anyone exposing a large TypeScript (or otherwise typed) client—GitHub, Salesforce, GCP, Stripe, custom internal APIs—could reuse a standard “search operations + get types” pattern instead of hand-crafting dozens of bespoke tools.

• MCP client / agent implementers
  Clients could implement first-class support for “library-backed discovery tools”: a unified UX for “search operations → inspect types → generate code”, regardless of whether the underlying server is Kubernetes, GitHub, or something else.

• End users and platform teams
  They get:

  • Safer, more predictable tool usage (because operations are discovered through structured search and are strongly typed).
  • Easier governance (because operations can be annotated with risk levels, scopes, and policy tags in a standard way).
  • Lower maintenance burden (because the server mostly tracks the upstream SDK, not a hand-maintained zoo of custom tools).

• The broader MCP ecosystem
  A standard pattern for typed library exposure would make it much easier to share examples, patterns, and even code across very different domains, accelerating adoption of MCP for “bring your own SDK” scenarios.

---

How might this be implemented at the protocol level?

At the protocol/spec level, this could be standardized as an optional “Library Discovery & Type Introspection” capability, built on top of the existing tools/list and tools/call messages, but with normative schemas and semantics for two well-known tool shapes (names are illustrative):

1. Standardized library search tool: <library>.searchOperations (or searchTools)

   This would be defined in the spec as a standard tool schema that servers implementing the library-discovery capability MUST provide (with any concrete name that fits the tool naming rules).

   • Input (conceptual):
     • libraryId: identifier for the underlying SDK (e.g. "kubernetes", "github", "salesforce").
     • query or structured filters: e.g. resourceType, action (read/list/write/delete), scope (cluster/project/repo), optional riskLevel or tags.
   • Output (per operation):
     • operationId: stable identifier tied to a specific SDK method or endpoint.
     • name / description: human-readable label for the operation.
     • tags: resource, verb, risk level, etc.
     • typeRefs: identifiers for input/output types (to be resolved via the type tool).
   • Semantics (to be spelled out in the spec):
     • Servers do not expose the whole SDK at once; they filter and rank operations based on the query and policy.
     • Servers may omit or down-rank dangerous or irrelevant operations (e.g. destructive or high-risk operations).
     • Clients are encouraged to present this as a “search and inspect operations” workflow, not as a giant flat tool list.
     • Results are returned as structured content (e.g. via structuredContent in the CallToolResult), in a JSON Schema–described format defined by the spec.

2. Standardized type introspection tool: <library>.getTypeDefinitions

   Likewise, this would be a standard tool shape whose input/output schema is defined in the spec.

   • Input (conceptual):
     • operationIds and/or typeIds returned from searchOperations.
   • Output:
     • A normalized type representation (e.g. JSON Schema, or a constrained schema derived from TypeScript/OpenAPI/JSON Schema) describing:
       • Request parameters (with names, types, optional/required, enums, etc.).
       • Response shape (again as a structured schema).
   • Semantics:
     • Designed for codegen: clients can render these into TypeScript, Python, etc., or feed them into planning tools.
     • Compatible with different type sources (TypeScript AST, OpenAPI, JSON Schema) as long as the output adheres to the agreed schema.
     • Types are delivered through structuredContent with a spec-defined JSON Schema, so clients know exactly how to interpret them.

Capabilities and integration with existing MCP messages

This would not require new JSON-RPC methods. Instead, the spec could:

• Define how this can be advertised today, using the existing experimental capability mechanism. For example, a server could already do:

 {
   "capabilities": {
     "tools": {
       "listChanged": true
     },
     "experimental": {
       "libraryDiscovery": {
         "version": "0.1.0"
       }
     }
   }
 }

Here, experimental.libraryDiscovery is an open-ended object, which is explicitly allowed by the current ServerCapabilities.experimental schema. Servers that set this flag would be asserting that they implement the standardized searchOperations / getTypeDefinitions tool shapes described above.

• Propose a protocol-level change for the future, via a SEP, to add a first-class libraryDiscovery capability (rather than only piggy-backing on experimental). For example, the spec could be extended so that ServerCapabilities.tools allows an additional libraryDiscovery object:

 {
   "capabilities": {
     "tools": {
       "listChanged": true,
       "libraryDiscovery": {
         "version": "1.0.0"
       }
     }
   }
 }

This second form would require a spec change (via a Standards Track SEP) because tools is currently defined with only listChanged and no additionalProperties. The SEP could define the exact shape and semantics of tools.libraryDiscovery and mark it as an official, non-experimental capability.

• In either case, the spec could then:
  • Require that servers advertising this capability:
    • Expose at least one standardized searchOperations-style tool and one getTypeDefinitions-style tool via tools/list.
    • Use the normative JSON Schemas and semantics defined in the spec for these tools’ inputSchema and outputSchema / structuredContent.
  • Encourage clients that see this capability to offer a dedicated UX flow for:
    • Searching operations.
    • Inspecting their types.
    • Generating and running code against the underlying SDK, with the usual tools/call semantics.

---

How might existing implementations serve as references?

At the implementation level, servers like ProDisco can serve as a reference implementation for such a capability:

• For Kubernetes, we introspect the official TypeScript client to:

  • Build an index of operations keyed by (group, version, kind, verb, scope, riskLevel, etc.).
  • Generate type metadata for each operation’s input and output types (currently via TypeScript types, but this could be emitted as JSON Schema to align with MCP).
  • Implement searchTools and getTypeDefinitions on top of that index, returning structured results that a client can use for codegen.

• For other SDKs (GitHub, Salesforce, GCP, etc.), a similar approach could be taken:

  • Use the TypeScript compiler API or existing OpenAPI/JSON Schema specs to extract types.
  • Map methods/endpoints to operationIds and associated type references.
  • Expose them via the same standardized MCP tools and capability.

This pattern is backwards-compatible and opt-in: existing MCP servers and clients continue to work as-is. Servers that implement this capability can advertise it via capabilities (initially under experimental, and potentially as a first-class tools.libraryDiscovery capability if a future SEP is accepted); clients that understand it can take advantage of richer discovery and type information.

If there’s community interest, I’d be keen to help turn this into a focused Standards Track SEP, following the process described in the SEP guidelines, with the Kubernetes-backed implementation acting as one of the reference implementations for the proposed protocol-level capability.

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Other

[harche]

On similar lines, https://www.anthropic.com/engineering/advanced-tool-use, check the section Programmatic Tool Calling section. I think if we want to keep this vendor neutral we should have it natively supported in MCP.