[Discussion] MCP server vs agentic skills for CALM — replace, or ship both?

# [Discussion] MCP server vs agentic skills for CALM — replace, or ship both?

_Related: #2600 (Track B3), #2562 (MCP consolidation Option B)._

## Context

#2600 Track B3 proposes consolidating two MCP servers (Java MCP in CALM Hub + `@calmstudio/mcp`) into one official `@finos/calm-mcp` per #2562 Option B.

A parallel approach has emerged in this repo's `calm-ai/skills/` directory: **agentic skills** (markdown skill files like `calm-arb-convert.md` + standalone utility scripts like `normalize_calm.py`) that any AI client can load **without an MCP server running**. The recent ARB-conversion work (PR #2545) demonstrates this pattern.

This issue is about choosing the right offering — or whether to ship both.

## The two patterns

### MCP server (`@finos/calm-mcp`)
- **What:** stdio/HTTP server exposing typed tool calls (`create_architecture`, `validate_architecture`, `hub_*`, etc.) via JSON-RPC
- **Where it runs:** as a separately-installed process, registered in client config (`claude_desktop_config.json`, `mcp_config.json`, `.vscode/mcp.json`, etc.)
- **Best for:** beginners — zero glue code, tool calls show up in the UI as discoverable actions
- **Constraints:** many enterprises and regulated environments **disallow MCP servers** (supply-chain liability, unaudited binary executing tool calls)

### Agentic skills (`calm-ai/skills/`)
- **What:** markdown skill files describing workflows + helper scripts (Python/TypeScript) the agent invokes directly
- **Where it runs:** loaded as context by the AI client; scripts executed as ordinary shell commands
- **Best for:** corporate / regulated users — no extra server process, fully auditable as text files in a repo, no separate install
- **Constraints:** requires an agent with skill-loading capability (Claude Code, Cursor, Windsurf, Copilot — varies in syntax); not as discoverable as named tool calls

## The decision

Three options:

1. **MCP-only** (current #2562 Option B). Single artifact, simpler matrix, but blocks regulated users.
2. **Skills-only.** Drop MCP entirely; ship the same capabilities as portable skills. Maximum compatibility but loses the "one tool call from your IDE" UX.
3. **Both — segmented by audience.** Ship `@finos/calm-mcp` for beginners + casual AI users, ship `calm-ai/skills/` as the canonical surface for corporate / regulated environments. Same underlying capabilities (e.g. validation, render, ARB-convert) — different access patterns.

## Open questions

- If we ship **both**, are skills the source of truth and MCP a thin wrapper, or vice versa? (Avoids the "two non-interoperable servers" problem #2600 calls out.)
- Do we have evidence of regulated users blocking MCP? (Anecdotal — worth confirming with FINOS member firms.)
- What's the maintenance cost of keeping skills in sync with MCP tool surface as the schema evolves?
- Does the `@calmstudio/mcp` → `@finos/calm-mcp` rename + `hub_*` tool additions in #2562 / #2600 B3 still proceed regardless, or wait for this decision?

## Proposal

Comment with views — particularly from FINOS member firms with views on MCP in their environments. The outcome of this discussion gates the shape of #2600 Track B3.

## References

- Parent: #2600 (Track B3)
- Related: #2562 (MCP consolidation Option B)
- Existing skill example: `calm-ai/skills/calm-arb-convert.md` (PR #2545)

Start by reading calm-ai/skills/calm-arb-convert.md and the related discussions in #2600 and #2562, then compare the documented MCP and skills surfaces. Done means reaching and recording a decision on MCP-only, skills-only, or both, including the source of truth, audience, and maintenance approach that will guide #2600 Track B3.

Written by the indexing model from the issue text.