The MCP surface is organized by the job a caller is trying to do. Tool registration follows the active runtime: core vocabulary and graph tools require the CDM runtime, while embedding, chat, knowledge-pack, and semantic-projection tools appear only when their prerequisites are available.
| Need | Start with | What it gives you |
|---|---|---|
| Inspect a known concept or relationship | Concept tools | Deterministic concept records, hierarchy, paths, edges, and standard mappings |
| Search with a specific retrieval signal | Search tools or embedding tools | Candidate records plus the signal used to retrieve them |
| Resolve free text with a ranked policy | concept_ground |
First successful resolver tier, ranked results, and grounding explanation |
| Preserve evidence for mapping review | Mapping tools | A candidate union, standard targets, hierarchy, relationships, and evaluation helpers |
| Prepare noisy clinical text | Text tools | Normalized, decomposed, cleaned, or disambiguated search phrases |
| Classify structured fields | domain_classify |
Best-effort OMOP domain hints for later retrieval |
| Analyze a source artifact before ingest | Source planning tools | Neutral tables, column roles, route decisions, warnings, and provenance |
| Find reusable operational guidance | Knowledge tools | Applicable knowledge-pack manifests and pack content |
| Turn a grounded concept into CDM rows | semantic_project |
Deterministic output rows, links, unresolved fields, or suppression reasons |
| Check what this deployment can do | System tools and --describe |
Backend availability, vocabulary catalogue, and registered MCP surfaces |
| Group | Tools | Availability |
|---|---|---|
| Concept | concept_get, concept_by_code, concept_ancestors, concept_descendants, concept_relationships, concept_equivalency_path, concept_path, concept_neighbors, concept_associations, concept_extended_inheritance, concept_map_to_standard |
CDM and graph runtime |
| Resolver | concept_ground |
Graph runtime |
| Search | concept_search_exact, concept_search_fulltext, concept_navigate_to_standard |
CDM vocabulary runtime |
| Mapping | concept_search_normalized, concept_candidate_bundle, concept_nearest_standard_ancestor, concept_mapping_context, concept_map_to_value, concept_resolve_mapping_expression, mapping_evaluate_candidates |
CDM runtime; some operations also require graph or embeddings |
| Embedding | embedding_index_status, embedding_neighbours, embedding_search, embedding_search_batch, embedding_encode |
omop_emb configured |
| Text | text_normalize, text_mapping_cleanup, text_decompose, text_disambiguate |
Chat model configured |
| Domain | domain_classify |
Chat model configured |
| Source planning | source_plan, source_plan_assisted |
Source-planning service; assisted path also needs chat |
| Knowledge | knowledge_catalogue, knowledge_pack |
Bundled or configured packs available |
| System | system_status, system_vocabulary_catalogue |
Always registered |
| Semantic projection | semantic_project |
semantic_projection_enabled = true |
The source-planning resources source-planning://canonical-headers, source-planning://column-roles, and source-planning://ingestion-strategies are also registered independently of the tool table. Text preprocessing prompts are available through MCP prompt discovery when the server starts.
MCP is the broad, discovery-oriented surface. REST intentionally exposes only curated workflow operations: candidate bundles and assisted source planning, plus /healthz. Direct Python callers should use app.services.* for domain workflows and should not import MCP tool modules to avoid a transport-shaped API.
The one service that is not attached to app.services is SemanticProjectionService: it has no adapter dependency and is constructed directly when the feature is enabled. The integration guide shows the three entry points; the concepts guide explains when each one is appropriate.
system_status and system_vocabulary_catalogue are always registered so a client can inspect the deployment before assuming optional capabilities exist. Other tool groups are omitted when their backing runtime is not configured. Use groundworkers --describe to inspect the exact active surface.
MCP tools return a JSON-safe error object rather than raising across the transport boundary:
{"error": true, "code": "ERROR_CODE", "message": "Human-readable description"}Common codes are NOT_FOUND, INVALID_INPUT, BACKEND_UNAVAIL, QUERY_ERROR, and INTERNAL_ERROR. Direct Python services raise GroundworkersError or ValueError instead; REST maps the same categories to HTTP responses.