RFC: Extension points for @theia/ai-mcp (transport / credentials / tool filter / client factory)

[dwbimstr]

RFC: Extension points for @theia/ai-mcp

Status (update): Consolidated to a single draft PR — #17376 — which now carries all four phases (A/B/C/D) as isolated commits on one branch. The per-phase PRs (#17378 B, #17379 C, #17380 D) have been closed to avoid duplicate review threads. Happy to re-split if maintainers prefer the staged shape — commits on #17376 map 1:1 with the closed PRs so it's a mechanical re-push. Please leave sequencing feedback on #17376.

Hi Theia maintainers — proposing four contribution-point types for @theia/ai-mcp so downstream projects (Sutra IDE, plus a handful of enterprise Theia distros) can plug into MCP transport, credential resolution, tool filtering, and client instantiation without forking the package.

Single draft PR with the full proposal: #17376

Motivation

@theia/ai-mcp today owns the entire MCP lifecycle: config, stdio/HTTP/SSE transports, credential reading via preferences, and client creation. That's the right default for most deployments, but it leaves no room for:

1. Alternative transports — WebSocket, in-process JS modules, gRPC, daemon-proxied.
2. OAuth / keychain / vault credential flows — anything beyond inlining a token into preferences.
3. Tool filtering / renaming / provenance — hiding dangerous tools from a multi-tenant config, de-duplicating tool names across servers.
4. Client wrappers — metrics, distributed tracing, structured logging, patched SDK forks.

We're currently forced to fork the package, and so are at least two enterprise distros we've talked to.

Proposal — four extension points

Each is a ContributionProvider<T> contribution point. Built-in providers ship with priority: 0 and match today's behaviour bit-for-bit.

Symbol	What it contributes
MCPTransportProvider	Custom transport selection keyed on MCPServerDescription
MCPCredentialResolver	OAuth / keychain / vault credential resolution with priority chain
MCPToolFilter	Filter / rewrite / suppress advertised tools before they hit ToolInvocationRegistry
MCPClientFactory	Swap the concrete Client wrapping for instrumentation

Full types + docstrings are in #17376. Quick preview:

export interface MCPTransportProvider {
    readonly id: string;
    readonly priority?: number;
    matches(description: MCPServerDescription): boolean;
    create(description: MCPServerDescription, signal: AbortSignal): Promise<MCPTransport>;
}

export interface MCPCredentialResolver {
    readonly id: string;
    readonly priority?: number;
    resolve(request: MCPCredentialRequest): Promise<string | undefined>;
}

export interface MCPToolFilter {
    readonly id: string;
    readonly priority?: number;
    filter(serverName: string, tool: ToolInformation): MCPToolFilterOutcome;
}

export interface MCPClientFactory {
    readonly id: string;
    readonly priority?: number;
    create(description: MCPServerDescription, transport: MCPTransport, context: MCPClientFactoryContext): Promise<MCPClient>;
}

Delivery shape

Now a single consolidated draft PR (#17376) with one commit per phase so reviewers can inspect each phase in isolation. Originally filed as four per-phase PRs (#17376 A, #17378 B, #17379 C, #17380 D) — the per-phase PRs have been closed and their commits rolled into #17376. Either shape is fine by me; please flag preference on #17376 and I'll re-push accordingly.

• Phase A (commit 4e45089) — public type surface only. ~370 LOC incl. tests. Zero existing code touched beyond common/index.ts re-exports.
• Phase B (commit afa7bc6) — wire ContributionProvider<T> lookup into MCPServerManager / MCPServer; add default built-ins for stdio, HTTP/SSE, passthrough tool filter, and @modelcontextprotocol/sdk client factory. All invariants of the existing test suite preserved.
• Phase C (commit e0ba0f9) — ${env:VAR} sentinel-backed credential resolver + preference-fallback resolver, wired as a priority chain. Unblocks OAuth / keychain plugins.
• Phase D (commit 362e3be) — documentation + migration guide under packages/ai-mcp/README.md and packages/ai-mcp/doc/MIGRATION.md.

Compatibility

• Zero observable change in Phase A; re-compiles clean; existing tests pass.
• After Phase B, every invariant of today's behaviour is reproduced by the default providers. The existing test suite continues to pass unchanged.
• After Phase C, the ${env:VAR} sentinel is strictly opt-in; preferences that carry inline credentials today keep working exactly as they do now.

Prior art in Theia

The extension-point shape mirrors Theia's existing ContributionProvider<T> pattern used for CommandContribution, FileServiceContribution, etc. Plugin authors already know how to contribute services; no new mental model. Default providers are bound with bindRootContributionProvider per the coding guideline.

Questions I'd like guidance on

1. Tool-filter semantics — should filters be able to add synthetic tools, or only filter / rewrite existing ones? Current proposal says "only filter", to keep the contract narrow; plugins can register synthetic tools directly into ToolInvocationRegistry if they want to add entries.
2. Credential resolver parallelism — I went with a priority chain (first non-undefined wins) rather than parallel resolution to keep refresh semantics predictable. Happy to revisit.
3. Exposing MCPClient events — onToolAdded, onClose, etc. are on the internal client today; should I promote them in the public interface, or leave that for a later RFC?
4. Sequencing — one consolidated PR (current state of RFC: @theia/ai-mcp extension points (transports, credentials, tool filters, client factory) #17376) or four per-phase PRs (closed feat(ai-mcp): default providers + server wiring (RFC phase B, #17375) #17378/17379/17380, re-pushable on request)?
5. Priority constants — I've used 0 / 50 / 100 as conventions. Promote to exported constants or keep as free integers like FrontendApplicationContribution ordering today?
6. Credential request shape — MCPCredentialRequest exposes { serverName, field, literal? }. Should field be a strongly-typed enum ('auth-token' | 'header' | 'custom') or kept as a free string?
7. Copyright attribution — the commits use Copyright (C) 2026 Sutra IDE contributors. — happy to adjust to whatever attribution convention maintainers prefer for external contributions. ECA sign-off pending.

Broader impact

Beyond Sutra, this unlocks:

• Enterprise Theia distros adding OAuth / vault support without forking.
• VS-Code-compat MCP extensions plugging in a WebSocket transport for browser-based Theia hosts behind reverse proxies.
• Tool-registry hygiene — de-duplication, visibility policy, and provenance tagging become plugin-land concerns instead of upstream patches.
• Consistent MCP debugging across the ecosystem via a single client-factory contribution point for structured-logging clients.

Full RFC doc with the gory detail (work breakdown, test strategy, API migration notes): https://github.com/dwbimstr/theia-sutra-ide/blob/main/docs/theia-mcp-extension-points-rfc.md

Happy to restructure, split, shrink, or rewrite any of this based on your guidance.

Thanks for maintaining @theia/ai-mcp; we've gotten a huge amount of mileage out of it.

[github-actions[bot]]

Hi @dwbimstr, thanks for starting this discussion! 👋

The Theia community will take a look soon. In the meantime, you might find helpful information in:

• 📖 Theia Documentation
• ❓ FAQ
• 💬 Previous Discussions

---

💙 Eclipse Theia is built and maintained by a community of contributors and sponsors. If Theia is valuable to your work, consider sponsoring the project. For professional support, training, or consulting services, learn more about available options.

[ndoschek]

Hi @dwbimstr,
Thanks for the thorough RFC and apologies for the delayed reply. We will take a look at the proposal and the consolidated draft PR and follow up there.
Thanks for putting this together!

[dwbimstr]

Update — RFC Q3 answered with implementation (commit 6deb0fe on #17376)

Hi @ndoschek @eneufeld — pushed an answer to the RFC's open Q3 ("expose onToolAdded / onClose on the public client surface, or defer?") rather than wait for review on it. Picked expose now, motivated by concrete downstream demand:

• Reactive UX is the dominant pattern. Polling is the wrong default for chat-adjacent UI. Sutra IDE — currently the most active downstream consumer of @theia/ai-mcp — switched its status-bar MCP indicator from a 4-second poll to an onDidChange-style push and dropped the perceived refresh latency from ~4s → ~50ms (reference commit). Without push-based events on the public MCPClient, every consumer rebuilds reactive state on top of a stale polling tick.
• Tiny surface, low risk. Two Event getters on MCPClient, plus emitter wiring in DefaultMCPClientFactory (with internal __fireDidAddTools / __fireClose hooks so today's in-tree MCPServer orchestration can drive them). Phase B's existing tests are unchanged; a new focused spec (default-mcp-client-factory.spec.ts, 6 cases) locks the contract.
• Plugin contract: plugins implementing MCPClient themselves provide their own emitter wiring. The fireDefaultClient* helpers return false for non-default clients, so plugin clients are never accidentally driven by the in-tree orchestration.

The other open RFC questions (Q1 add-vs-filter, Q2 credential parallelism, Q4 sequencing, Q5 priority constants, Q6 credential request shape, Q7 copyright) didn't gather new evidence from the downstream work — leaving those open for your judgement on this PR.

Diff: 5 files, +224/−1. Happy to split, shrink, or revert if maintainers prefer Q3 stays "later RFC" — easy to drop the commit.

[musaabhasan]

The four extension points make sense, especially if Theia needs to support enterprise MCP deployments where transport, credentials, and tool policy are rarely one-size-fits-all.

I would be careful about the order of responsibility:

1. Transport/client factory creates the connection boundary.
2. Credential resolver supplies identity without exposing raw secrets to prompt context.
3. Tool filter applies allow/deny policy before tools are visible to the agent.
4. Runtime hooks observe tool additions, closure, and capability changes.

The security-sensitive part is the tool filter. It should be able to filter by server identity, tool name, input schema, write capability, resource scope, and workspace trust level. A string-name allowlist is useful, but insufficient for MCP servers that expose broad tools with dangerous parameter combinations.

For downstream IDEs, it would also help if the public API could expose an effective MCP manifest after filtering. That makes diagnostics and user consent clearer: "these are the tools this agent can actually see and why."

[dwbimstr]

@musaabhasan - this is great feedback. let me think through the changes i would need to do for this. I also been doing a lot around agentgateway (solo.io) work. let me give another pass at security aspects and get back. Thank you for replying - really appreciate that.

[dwbimstr]

@musaabhasan thanks for the careful read — pushed two follow-ups to #17376 today that pick up two of your three points.

98e99d5 adds README sections for the responsibility flow (transport → credentials → tool filter → runtime hooks) and gateway-aware deployments (calling out agentgateway since you'd already gone there). Spells out the security invariant you flagged — credentials live as transport headers, never in prompt context.

d6f99a0 adds onWillInvokeTool / onDidInvokeTool events on MCPClient — the call-site half of your runtime-hooks point. Sibling to the onDidAddTools / onClose events that already landed. Lets consumers attach OpenTelemetry spans / structured logs / runtime RBAC checks without replacing the whole client factory.

What I'm sketching next, holding for your input on shape:

• A wider MCPToolFilterContext so filters see serverName, serverDescription, tool, and workspaceTrustLevel (sourced from Theia's WorkspaceTrustService). That covers your "workspace trust" point. Also adding originalName + provenance fields on ToolInformation so federating gateways can preserve upstream identity through rename/filter chains.
• A HeadersHelperCredentialResolver — git credential-helper-style shell command that returns dynamic headers, gated on workspace trust for project-scoped configs. Closes the gap between bare ${env:VAR} and full OAuth.
• An effective-manifest API (getEffectiveTools() with filter trace) for the consent / diagnostics surface you described. Want to do it as a follow-up PR once the filter-context shape settles — depends on the bits above to have anything meaningful to expose.

One honest question on writeCapability / resourceScope — MCP doesn't standardize annotations for either yet, so I'd be adding optional empty slots. Would you actually use them today (i.e. you have a server / gateway that already emits something we could key off), or is it more "want it on the roadmap"? The answer changes whether I push something now or wait for the spec / a concrete consumer.

Happy to push the filter-context + headersHelper bits onto the same PR or split into a follow-up — let me know your preference.

[dwbimstr]

Quick ping — both this thread and #17376 have been quiet for ~3 weeks since the F / H / I commits landed.

@musaabhasan, did the responsibility-flow + MCPToolFilterContext work end up covering your asks, and is writeCapability / resourceScope still something you'd want pushed forward?

@ndoschek @eneufeld, no rush at all — just a quick steer on sequencing (whether to keep F/H/I stacked on the same PR or split them off into a follow-up) would help me plan the next pass. Happy either way.