mcp-ecosystem

name

mcp-ecosystem

description

Access 79 tools across 17 modules from the local MCP Ecosystem server to fetch live methodology, templates, components, and complete OFFICIAL DOCUMENTATION for spec-kit, anthropics-skills, agent-framework, gh-aw, agents-md, github-copilot-docs, the five Backstage modules, plus full official docs: Microsoft Learn (federated — all of Azure/AKS/AI Foundry/CAF/WAF), VS Code, GitHub (docs.github.com), Anthropic/Claude, Azure Cloud Adoption Framework (CAF) and Well-Architected Framework (WAF). USE FOR: Spec-Driven Development phases and commands, Microsoft Agent Framework patterns, GitHub Agentic Workflows (gh-aw), AGENTS.md format and section templates, GitHub Copilot documentation and customization, Anthropic docs, Backstage documentation, Software Catalog, Software Templates, plugin directory, Backstage UI and Storybook, searching all of Microsoft Learn (Azure, AKS, AI Foundry, CAF, WAF), VS Code docs, GitHub docs (Actions, GHAS, OIDC, Packages), and the Claude developer docs — to support agents during the whole installation and at runtime. Also USE FOR wiring the AI Chat (agent-api) to the ecosystem so agents can ground answers in real upstream docs. DO NOT USE FOR general web search, infra MCP servers (azure/github/terraform/kubernetes — see mcp-config.json), or non-reference queries.

MCP Ecosystem

The MCP Ecosystem is the platform's own Model Context Protocol (MCP) server. It exposes 79 tools across 17 modules that fetch live, cached reference data (methodology, format specs, templates, components, plugin catalogs, and docs) from curated upstream sources. It is the L3 Context Engineering surface that lets Open Horizons agents — and the Backstage AI Chat — ground their answers in real, current documentation instead of model recall.

Two different "MCP" surfaces — do not confuse them:

• MCP Ecosystem (this skill): the implemented TypeScript server in mcp-servers/ serving documentation/reference tools.
• Infra MCP policy (mcp-servers/mcp-config.json): the access policy mapping runtime agents to operational MCP servers (azure, github, terraform, kubernetes, helm, …). That is a separate concern.

When to use this skill

Load this skill when you need to:

• Retrieve Spec-Driven Development phases, commands, philosophy (spec-kit).
• Look up Microsoft Agent Framework patterns, samples, declarative agents.
• Get GitHub Agentic Workflows (gh-aw) patterns and security guidelines.
• Fetch the AGENTS.md format spec and section templates.
• Read GitHub Copilot docs, customization, and extensions.
• Search the Anthropic skills catalog and specs.
• Query Backstage docs, Software Catalog, Software Templates, API reference.
• Browse the Backstage plugin directory (core + community).
• Inspect Backstage UI components and Storybook stories.
• Read Spotify Portal docs and discover github.com/backstage repos.
• Search all of Microsoft Learn (Azure, AKS, AI Foundry, CAF, WAF) via federation (mslearn_*), and fetch full Learn articles by URL.
• Search VS Code docs (vscode_*) and GitHub docs (ghdocs_* — Actions, GHAS, OIDC, Packages) — essential during installation.
• Search the complete Anthropic/Claude documentation (anthropicdocs_*).
• Search CAF (caf_*) and WAF (waf_*) for adoption + design guidance.
• Wire the AI Chat / agent-api so agents can call the ecosystem.

Do not use it for general web search, for infra/operational MCP servers, or for anything that is not upstream reference data.

The server at a glance

Property	Value
Server name	mcp-ecosystem
Source	mcp-servers/ (TypeScript, MCP SDK + Express)
Transport	Streamable HTTP (StreamableHTTPServerTransport)
Endpoint	http://localhost:3100/mcp
Health	GET http://localhost:3100/health → { "status": "ok", "sessions": N }
Modules / tools	17 modules · 79 tools
Cache	On-disk JSON cache (CACHE_DIR, default 1h TTL via CACHE_TTL_MS)
Auth to upstreams	Optional GH_TOKEN raises GitHub raw/API rate limits
Image	ohorizons GHCR: mcp-ecosystem (see CHANGELOG for current tag)

Where it runs (two phases)

The same server image is used in two moments of the platform lifecycle:

• Phase 1 — Installation (LOCAL): runs on the operator's machine via Docker during platform build, so the Copilot agents (@deploy, @terraform, …) can ground build-time decisions in real upstream docs. Ephemeral; never shipped to Azure.
• Phase 2 — Runtime (AZURE / AKS): deployed to the ai-services namespace (gated to enable_mcp_ecosystem), where the Backstage AI Chat calls it to ground developer answers. The AI Chat (agent-api) lives in the same namespace and reaches it at http://mcp-ecosystem.ai-services.svc.cluster.local:3100/mcp; a NetworkPolicy restricts :3100 to the agent-api pod.

Full deployment detail: mcp-servers/ARCHITECTURE.md.

Run it locally

cd mcp-servers
make up        # docker compose up -d  (builds + starts on :3100)
make health    # curl http://localhost:3100/health  → {"status":"ok"}
make logs      # follow logs
make down      # stop

The .env file is optional. The host port is configurable to avoid collisions (Grafana Loki also defaults to 3100):

MCP_ECOSYSTEM_PORT=3101 docker compose up -d

Environment variables (all optional): PORT (3100), CACHE_DIR, CACHE_TTL_MS (3600000), GH_TOKEN, MCP_ECOSYSTEM_PORT (local host port).

Tool catalog (17 modules · 79 tools)

Group A — Agent & AI frameworks (6 modules · 26 tools)

Module	Prefix	Tools
spec-kit (5)	speckit_	get_phases, get_commands, get_methodology, get_philosophy, search
anthropics-skills (5)	anthropics_	list_skills, get_skill, get_skill_template, search_skills, get_spec
agent-framework (4)	agentfw_	get_patterns, get_sample, search_docs, get_declarative_agents
gh-aw (4)	ghaw_	get_workflow_patterns, get_security_guidelines, get_contributing, get_agents_md
agents-md (3)	agentsmd_	get_format_spec, get_readme, get_section_templates
github-copilot-docs (5)	copilotdocs_	list_sections, get_page, search, get_customization, get_extensions

Group B — Backstage ecosystem (5 modules · 31 tools)

Module	Prefix	Tools
backstage-docs (7)	backstagedocs_	list_sections, get_page, search, get_catalog, get_software_templates, get_plugins, get_api_reference
backstage-plugins (6)	backstageplugins_	list_directory, list_community, get_community_plugin, search_community, list_core, get_core_plugin
backstage-ui (8)	backstageui_	list_components, get_component, get_api_report, get_readme, get_changelog, storybook_list_stories, storybook_get_story, storybook_search
spotify-backstage (6)	spotifybackstage_	list_sections, get_page, get_portal_docs, get_plugins_docs, get_core_features, discover_links
backstage-org (4)	backstageorg_	list_repos, get_repo_readme, search_repos, get_backstage_plugins

Group C — Official documentation (6 modules · 22 tools)

Module	Prefix	Tools
microsoft-learn (3, federated)	mslearn_	search, code_search, fetch — ALL of Microsoft Learn incl. CAF/WAF
vscode-docs (4)	vscode_	list_sections, list_pages, get_page, search
github-docs (4)	ghdocs_	list_sections, list_pages, get_page, search (Actions, GHAS, OIDC, Packages)
anthropic-docs (3)	anthropicdocs_	index, get_page, search (complete Claude docs)
azure-caf (4)	caf_	list_sections, list_pages, get_page, search
azure-waf (4)	waf_	list_sections, list_pages, get_page, search

microsoft-learn federates the official Microsoft Learn MCP (learn.microsoft.com/api/mcp) for complete, always-current coverage of every Microsoft product. azure-caf/azure-waf additionally cache the framework docs for offline use during the local installation phase.

Tool names are the prefix + the suffix shown, e.g. speckit_get_phases, mslearn_search, backstageui_storybook_search.

How the AI Chat uses the ecosystem

The Backstage AI Chat (agent-api) ships a thin Python client and advertises a small, curated set of ecosystem tools to the model so agents can ground answers:

• Client: backstage/server/agent-api/tools/mcp_ecosystem.py
• Advertised to the model (orchestrator, sentinel, lighthouse, guardian, forge, pipeline):
  • ecosystem_list_tools — discover everything the server exposes.
  • ecosystem_call_tool(name, args) — call any of the 79 tools directly.
  • search_microsoft_learn(query) → mslearn_search (federated, all of Learn)
  • fetch_microsoft_learn(url) → mslearn_fetch
  • search_backstage_docs(query) → backstagedocs_search
  • search_copilot_docs(query) → copilotdocs_search
  • search_github_docs(query, section) → ghdocs_search
  • search_vscode_docs(query, section) → vscode_search
  • search_anthropic_docs(query) → anthropicdocs_search
  • search_caf(query, section) → caf_search
  • search_waf(query, section) → waf_search
  • get_spec_kit_methodology() → speckit_get_methodology

The client targets MCP_ECOSYSTEM_URL (default http://localhost:3100/mcp). In-cluster, point it at the mcp-ecosystem Service. If the server is unreachable, the client degrades gracefully and the chat answers without grounding rather than failing.

Calling a tool directly (JSON-RPC over HTTP)

curl -s http://localhost:3100/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"speckit_get_phases","arguments":{}}}'

List all tools:

curl -s http://localhost:3100/mcp -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Workflow for agents

1. Discover — if unsure which tool fits, call ecosystem_list_tools first.
2. Pick the narrowest tool — prefer *_search for discovery, then a get_* tool to fetch the specific page/spec/template.
3. Cite the source — ecosystem tools return upstream content; attribute it.
4. Cache-aware — responses are cached (~1h). For "latest", note staleness.
5. Stay in scope — for live cloud state use the infra MCPs, not this server.

Operational notes

• Caching: results persist under CACHE_DIR with CACHE_TTL_MS TTL to keep upstream rate limits low and responses fast. Delete the cache volume to force a refresh.
• Rate limits: set GH_TOKEN to raise GitHub raw/API limits for the backstage-org, backstage-plugins, and *_get_readme style tools.
• Adding a module: create mcp-servers/src/tools/<name>.ts exporting a register<Name>Tools(server, cache) function, register it in mcp-servers/src/index.ts, and keep the README, this skill, and mcp-servers/ARCHITECTURE.md counts in sync.
• Health/readiness: GET /health is used for container and K8s probes.

Related

• Architecture deep-dive: mcp-servers/ARCHITECTURE.md
• Server README: mcp-servers/README.md
• Usage guide: mcp-servers/USAGE.md
• AI Chat client: backstage/server/agent-api/tools/mcp_ecosystem.py
• Infra MCP policy (different surface): mcp-servers/mcp-config.json