Skip to content

MCP Service Contracts

The private docs site is a source-of-truth contract surface for both humans and future enterprise agents. Agents that provision MCP services should treat these docs as the semantic layer and use the machine-readable files for tool generation.

Source-Of-Truth Order

Use this order when building an MCP server or retrieval index over LeafEnterprise:

  1. docs-site/docs/machine/api-reference.json for structured route, family, queue-action, and ownership metadata.
  2. Generated route-family pages under docs-site/docs/api/routes/ for semantic context and human-readable endpoint behavior.
  3. Backend system pages under docs-site/docs/backend-libraries/ for deterministic business rules and evidence boundaries.
  4. Existing architecture notes under docs/architecture/ for dated decision history.
  5. Source code when implementing or validating exact runtime behavior.

If the generated machine contract and prose disagree, treat the generated machine contract as the current API index and inspect source before changing behavior.

MCP Tool Naming

Generated MCP tools should use stable, descriptive names:

leafenterprise.<family>.<method>.<path_slug>

Examples:

leafenterprise.report_deliverables.get_client_report_context
leafenterprise.itr_workbench.post_it_request_run_plan
leafenterprise.agent_workbench.post_agent_task_dispatch
leafenterprise.optimization_ai.post_module_copilot

Tool Description Requirements

Every generated tool description should include:

  • method and path,
  • route family,
  • backend handler,
  • auth posture,
  • required query/body fields,
  • response sections,
  • blocked/failure semantics,
  • source modules,
  • sensitivity warning.

Security Boundaries

MCP tools must not expose:

  • Salesforce tokens or body URLs,
  • Microsoft Graph tokens or raw download URLs,
  • Azure SQL, AWS SQL, ADLS, Service Bus, Key Vault, or model provider credentials,
  • local OneDrive or share-drive paths,
  • raw client data beyond the endpoint's documented browser-safe payload.

Retrieval Chunking Guidance

For semantic indexing:

  • index each generated route-family page as one high-level document,
  • also chunk each endpoint section beginning with ###,
  • include machine/api-reference.json as structured metadata,
  • preserve frontmatter fields such as semantic_type, keywords, and description,
  • attach source path, method, route family, and handler as retrieval metadata.

Agent Use Pattern

An agent should:

  1. Read llms.txt to discover the docs surface.
  2. Read machine/api-reference.json for tool candidates.
  3. Retrieve the relevant route-family page for operational semantics.
  4. Retrieve the backend library page for business logic and evidence rules.
  5. Call the backend API only through trusted service credentials or backend-owned MCP tools.

Provisioning Acceptance Criteria

An MCP service over LeafEnterprise APIs is acceptable only when:

  • every exposed route appears in machine/api-reference.json,
  • every route has a route-family page,
  • protected routes require backend-held credentials,
  • tool calls log route, actor, parameters, and trace id where supported,
  • tool descriptions clearly mark blocked states and evidence requirements,
  • generated tools do not invent write capability beyond the documented endpoint.