| 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
make health
make logs
make down
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_fetchsearch_backstage_docs(query) → backstagedocs_searchsearch_copilot_docs(query) → copilotdocs_searchsearch_github_docs(query, section) → ghdocs_searchsearch_vscode_docs(query, section) → vscode_searchsearch_anthropic_docs(query) → anthropicdocs_searchsearch_caf(query, section) → caf_searchsearch_waf(query, section) → waf_searchget_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
- Discover — if unsure which tool fits, call
ecosystem_list_tools first.
- Pick the narrowest tool — prefer
*_search for discovery, then a
get_* tool to fetch the specific page/spec/template.
- Cite the source — ecosystem tools return upstream content; attribute it.
- Cache-aware — responses are cached (~1h). For "latest", note staleness.
- 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
