MCP Protocol & Progressive Tool Discovery

A host owns the model interaction, user experience, consent, and server selection. A client implements one protocol relationship to an MCP server. A server exposes tools, resources, prompts, and extension-defined behavior. ^S01

Core primitives

Transports

Stable versus 2026 release candidate

Boundary matrix

Selection favors publisher authority, executable public code, substantial public adoption, and architectural significance. Popularity is corroborating evidence—not a security certification.

The host retrieves definitions from MCP servers but keeps most schemas outside the model context. The model searches concise capability metadata, inspects selected definitions, and then calls normal typed tools. The official guidance describes this as catalog → inspect → execute. ^S03

Activation policy

Progressive disclosure levels

Catalog strategy by scale

Canonical catalog record

export interface ToolCatalogRecord {
  // Stable invocation identity
  id: string;                 // serverId::originalToolName
  serverId: string;
  originalName: string;
  namespace: string;
  schemaHash: string;
  sourceRevision: string;

  // Retrieval representation
  title: string;
  shortDescription: string;
  keywords: string[];
  syntheticQueries: string[];
  negativeQueries: string[];
  entityTypes: string[];
  operationVerbs: string[];
  parameterNames: string[];
  outputConcepts: string[];
  relatedToolIds: string[];

  // MCP contract
  inputSchema: Record<string, unknown>;
  outputSchema?: Record<string, unknown>;
  annotations?: Record<string, unknown>;

  // Governance and operations
  operationClass: "read" | "write" | "execute" | "approve";
  reversibility: "reversible" | "compensatable" | "irreversible";
  riskClass: "low" | "moderate" | "high" | "critical";
  requiredScopes: string[];
  requiredEntitlements: string[];
  allowedEnvironments: string[];
  dataClasses: string[];
  enabled: boolean;
  healthStatus: "healthy" | "degraded" | "unavailable";
}

Retrieval document

Do not embed only the publisher’s description. Build a multi-field representation containing the canonical name, aliases, curated purpose, verbs, entities, parameters, outputs, example user requests, negative examples, and workflow relationships. Multi-field research shows that function, inputs, and outputs carry different retrieval signals. ^S28S30

Search contract

{
  "query": "find latency metrics for publishing API",
  "operationClass": "read",
  "environment": "production",
  "limit": 5
}

{
  "queryId": "qry_01J...",
  "matches": [{
    "toolId": "grafana::query_prometheus",
    "summary": "Run a read-only PromQL query.",
    "keyInputs": ["dataSourceId", "query", "start", "end"],
    "riskClass": "low",
    "whyMatched": ["latency", "time-series", "Prometheus"]
  }]
}

Authorization-aware retrieval skeleton

export async function discoverTools(
  principal: PrincipalContext,
  intent: CapabilitySearchIntent,
  deps: DiscoveryDependencies,
): Promise<ToolCard[]> {
  // Tool existence is protected information. Filter before search.
  const authorizationFilter =
    await deps.policy.getAuthorizedToolFilter(principal);

  const query = buildStructuredQuery(intent);

  const [lexical, semantic] = await Promise.all([
    deps.lexicalSearch(query, authorizationFilter, 30),
    deps.semanticSearch(query, authorizationFilter, 30),
  ]);

  const fused = reciprocalRankFusion([lexical, semantic]);
  const reranked = await deps.rerank(intent, fused.slice(0, 20));
  const selected = selectDiverseCandidates(reranked, dynamicK(intent));

  return deps.catalog.getToolCards(selected.map(x => x.toolId));
}

Provider adapter strategy

Catalog synchronization

1. Connect and negotiate the supported protocol generation.
2. Page through every tools/list result.
3. Normalize JSON Schema and compute a stable schema hash.
4. Enrich with curated retrieval and governance metadata.
5. Index lexical and semantic representations.
6. Process notifications/tools/list_changed and periodic reconciliation.
7. Invalidate loaded schemas when compatibility, authorization, or security changes.
8. Reauthorize every tools/call regardless of discovery state.

Threat model

Identity and delegation envelope

{
  "humanSubject": "user-123",
  "workloadIdentity": null,
  "agentId": "incident-triage-agent",
  "hostId": "enterprise-assistant",
  "tenantId": "league-platform",
  "delegationChain": ["host", "specialist-agent", "mcp-gateway"],
  "targetServer": "grafana-production",
  "tool": "query_prometheus",
  "environment": "production",
  "policyVersion": "ai-policy-2026.07.3",
  "approvalId": null,
  "traceId": "00-..."
}

Mutating tool contract

AWS-first deployment

Initial release objectives

Evaluation corpus requirements

• Exact-name and known-resource requests.
• User vocabulary that differs from API terminology.
• Create/delete, enable/disable, publish/unpublish confusion sets.
• Read versus write and planning versus execution.
• Production versus non-production and project or tenant scope.
• Unauthorized but semantically relevant tools.
• No suitable tool, deprecated tool, renamed tool, and server outage.
• Multi-step tasks searched one step at a time.
• Prompt-injection content in resources, descriptions, and outputs.

Patterns to avoid

Claim ledger

Source registry

Maintenance procedure

1. Recheck all normative and time-sensitive official sources.
2. Diff specification and extension versions against the artifact’s sourceRevision.
3. Re-run public-code architecture checks for changed configuration, authentication, and discovery behavior.
4. Re-run the retrieval and invocation evaluation corpus against supported models.
5. Update claim confidence, sources, and update triggers.
6. Increment semantic versioning: major for architectural conclusions, minor for material evidence or sections, patch for corrections.
7. Preserve the prior artifact and record the change summary.