MCP, APIs, and Tool Connectivity
1. Purpose
AI capabilities in the Site Application need a common integration boundary for tools, internal APIs, external APIs, search services, workflows, and enterprise systems.
The platform should support multiple interface types rather than forcing every integration into MCP.
2. Connectivity Types
| Type | Primary Purpose | Typical Consumer |
|---|---|---|
| REST/HTTP API | Application-to-application operations | Site services, automation, agents |
| OpenAPI description | Machine-readable HTTP API contract | Developers, generated clients, agent tooling |
| MCP | AI-oriented protocol for tools/resources/prompts | AI hosts/agents/clients |
| Webhook | Event callback | Automation/workflow engine |
| Event/message | Asynchronous integration | Services, agents, automations |
| SDK | Native programming integration | Site component/runtime |
| Custom URL | Web page or endpoint integration | Browser/embedded component |
3. MCP Technical Model
MCP is not a generic API response structure and should not be described as "convert every API response to MCP JSON."
MCP is a protocol with a client-host-server architecture. The base protocol uses JSON-RPC 2.0, with lifecycle and capability negotiation. MCP servers can expose three primary kinds of primitives:
- Tools: operations a model can invoke;
- Resources: contextual data an application can retrieve;
- Prompts: reusable prompt templates exposed by the server.
flowchart TD
H[["AI Host / Site Runtime"]]:::model --> C[["MCP Client"]]:::process
C --> J["JSON-RPC over MCP Transport"]:::process
J --> S[["MCP Server"]]:::external
S --> T["Tools"]:::external
S --> R[("Resources")]:::store
S --> P["Prompts"]:::process
classDef process fill:#EEF2F7,stroke:#475569,stroke-width:1px,color:#0B1220
classDef model fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#0B1220
classDef store fill:#CCFBF1,stroke:#0F766E,stroke-width:1px,color:#0B1220
classDef external fill:#F1F5F9,stroke:#64748B,stroke-width:1px,color:#0B1220,stroke-dasharray:4 3
4. OpenAPI vs MCP
OpenAPI and MCP solve different problems.
| Area | OpenAPI | MCP |
|---|---|---|
| Defines | HTTP API contract | AI tool/context protocol |
| Transport | HTTP-based API operations | stdio or Streamable HTTP per MCP standard transport model |
| Consumer | Developers, services, generators | AI hosts/clients/agents |
| Core concept | Paths/operations/schemas | Tools/resources/prompts |
| Authentication | Defined/integrated at API layer | Protocol and transport auth patterns |
| Relationship | Existing API can be described with OpenAPI | Selected API operations can be exposed as MCP tools |
Recommended architecture:
flowchart TD
A[["Existing REST API"]]:::external --> O["OpenAPI Specification"]:::process
A --> M[["MCP Adapter / Server"]]:::process
M --> T1["Approved Tool 1"]:::govern
M --> T2["Approved Tool 2"]:::govern
classDef process fill:#EEF2F7,stroke:#475569,stroke-width:1px,color:#0B1220
classDef govern fill:#FFE4E6,stroke:#BE123C,stroke-width:1px,color:#0B1220
classDef external fill:#F1F5F9,stroke:#64748B,stroke-width:1px,color:#0B1220,stroke-dasharray:4 3
Do not automatically expose the entire API surface as model-callable tools.
5. Tool Contract
Every AI-callable tool should have a bounded contract.
name: create-maintenance-request
description: Create a maintenance request for an approved asset.
input_schema:
type: object
required: [asset_id, reason]
properties:
asset_id:
type: string
reason:
type: string
priority:
type: string
enum: [low, medium, high]
execution:
connector_ref: eam-create-request
authorization:
required_permission: maintenance.request.create
approval:
mode: conditional
6. API Connector Configuration
A Standard Package connector should hold configuration, not application code.
Recommended fields:
| Property | Purpose |
|---|---|
| Base URL | Service endpoint |
| Authentication type | OAuth2, API key, mTLS, managed identity, etc. |
| Secret reference | Credential pointer, never raw secret in docs |
| OpenAPI reference | Contract/schema location where available |
| Timeout | Network/execution timeout |
| Retry policy | Retry behavior |
| Rate limits | Provider/service limits |
| Allowed operations | Explicit allow-list |
| Environment | Dev/test/prod endpoint selection |
| Network policy | Proxy/firewall/internal zone |
7. Authentication
Supported patterns should include:
- API keys;
- OAuth 2.0 delegated access;
- OAuth 2.0 client credentials/app-only access;
- managed/workload identities where supported;
- mutual TLS where required;
- signed service tokens;
- provider-specific mechanisms.
A raw API key should be used only when that is the service's appropriate supported mechanism. Per-user delegated OAuth is preferable when actions must preserve the user's identity and permissions.
8. Tool Safety
An AI tool must not be granted authority merely because the underlying API exists.
Minimum controls:
- operation allow-list;
- input validation;
- authorization at execution time;
- output validation;
- rate limiting;
- timeout/retry controls;
- idempotency where applicable;
- audit record;
- correlation ID;
- approval for consequential actions;
- secret isolation;
- network egress restrictions.
9. Search and External Services
Search APIs, model APIs, and external enterprise services can be represented as connectors and then exposed to an assistant or agent as approved tools.
flowchart TD
A[["Agent"]]:::model --> S["Search Tool"]:::process
S --> SC[["Search Connector"]]:::process
SC --> API[["Search API"]]:::external
A --> AT["Asset Tool"]:::process
AT --> AC[["Site API Connector"]]:::process
AC --> SS[["Site Service"]]:::external
A --> W["Work Order Tool"]:::process
W --> EC[["ERP / EAM Connector"]]:::process
EC --> ES[["Enterprise System"]]:::external
classDef process fill:#EEF2F7,stroke:#475569,stroke-width:1px,color:#0B1220
classDef model fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#0B1220
classDef external fill:#F1F5F9,stroke:#64748B,stroke-width:1px,color:#0B1220,stroke-dasharray:4 3
10. MCP Server for Site APIs
A Site MCP server should expose a curated semantic tool layer over the platform, not a raw mirror of controllers.
Recommended flow:
flowchart TD
S[["Site API / Domain Service"]]:::external --> M[["MCP Tool Adapter"]]:::process
M --> N["Schema normalization"]:::process
M --> A["Auth context"]:::govern
M --> P["Policy check"]:::govern
M --> C["Audit / correlation"]:::govern
N --> R[["Agent Runtime"]]:::model
A --> R
P --> R
C --> R
classDef process fill:#EEF2F7,stroke:#475569,stroke-width:1px,color:#0B1220
classDef model fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#0B1220
classDef govern fill:#FFE4E6,stroke:#BE123C,stroke-width:1px,color:#0B1220
classDef external fill:#F1F5F9,stroke:#64748B,stroke-width:1px,color:#0B1220,stroke-dasharray:4 3