MCP Server

Understand Model Context Protocol, how the MCP Server connects external agents to Zild and which API operations it publishes.

What is an MCP Server?

MCP stands for Model Context Protocol: an open protocol that standardizes how AI applications connect to tools and context sources. An MCP Server is the program that offers these capabilities to a compatible client. It describes the available tools, what they do and which arguments they accept, then receives calls and returns results.

For Zild, an external agent can look up a contact, find conversations, submit a document for processing or run a platform agent. The client discovers these operations through a common format, reducing the need for a custom integration for each REST route.

MCP organizes communication. The AI model still runs through its host application, and business rules remain in Zild API. The server does not grant new permissions or independently decide which actions a user intends to perform.

How the client, agent and server work together

  1. AI application (host): receives user requests and coordinates the model and tools.
  2. MCP client: connects the application to the server and exchanges protocol messages.
  3. Zild MCP Server: provides the catalog and translates tool calls into API requests.
  4. Zild API: applies authentication, permissions, tenant resolution, validation and business rules before returning the result.
User → AI application → MCP client
                           ↓
                    Zild MCP Server
                           ↓
                       Zild API
                           ↓
                       Tenant data

For example, when asked to “look up contact 123”, the application can select the tool for GET /Contact/{id}, supply the ID and present the authorized Zild response to the user.

How MCP and OpenAPI complement each other

A REST API defines routes, HTTP methods, request bodies and responses. OpenAPI describes these contracts in a structured document. MCP provides an AI client with a catalog of functions, each with a name, description and input schema, and a standard way to execute them.

In Zild, the final OpenAPI document produced by Swagger is the catalog source. Route, query and body parameters become tool arguments, and execution calls the original HTTP route. The API retains its business rules and contract documentation.

The protocol also supports resources (context sources) and prompts (reusable interaction templates). The first Zild version publishes tools generated from API operations; it does not provide a separate resources or prompts catalog.

See the official MCP architecture and MCP server concepts.

What Zild MCP exposes

Analysis of the OpenAPI bundled with this site identified 137 operations across 79 routes: 51 GET, 42 POST, 22 PUT and 22 DELETE. The implemented adapter maps each document operation to a tool.

The catalog covers CRM, agents, voice, Insight, Assist, conversations, documents, Flow, MCP connections, departments, quotas, consumption and webhooks. It includes queries and actions that change data or initiate communication with other people. Authorization is checked on every execution.

See the complete MCP operation catalog for expected tool names, methods, routes and API contract links. Counts describe the analyzed file; each environment uses the Swagger document of its deployed version. The endpoint remains disabled by default until an operator enables it.

Connection and authentication

Configure a Streamable HTTP client to connect to /mcp on the enabled Zild API origin. The transport does not maintain persistent sessions. Send one existing credential on every request:

X-API-Key: YOUR_USER_API_KEY

Authorization: Bearer YOUR_ACCESS_TOKEN

Use the HTTPS URL supplied by the environment operator. This version does not implement OAuth discovery, consent or token issuance for new MCP clients. The client must support configuring authentication headers.

Discovering and executing tools

The catalog comes from the same Swagger/OpenAPI used for API documentation. Hidden actions and publication filters are respected; each published operation becomes a tool, including write operations.

Discover tools with tools/list, then use tools/call with the returned tool name and inputSchema. Names follow zild_<method>_<normalized-route>_<hash>.

The catalog is shared by authenticated clients. Execution goes through API authentication, permissions and tenant resolution again. A tool appearing in the catalog does not grant access to a resource.

Arguments and files

Supply only the groups present in the tool schema: path, query, body and, when published, header. Illustrative example:

{
  "path": {
    "id": 123
  },
  "query": {
    "page": 1
  },
  "body": {
    "name": "Example"
  }
}

JSON, multipart/form-data and application/x-www-form-urlencoded are supported. Files use fileName, contentBase64 and contentType inside the body file field. Authentication headers belong to the transport, not tool arguments.

Limits and responses

  • MCP request: 16 MiB; individual file: 10 MiB.
  • API response: 2 MiB; use filters and pagination.
  • Timeout: 120 seconds.
  • Default limit: 60 requests per minute per credential, per instance, configurable by the operator.

Results preserve API JSON as text content. Unsuccessful HTTP responses return isError with the HTTP status. There are no automatic retries or additional idempotency guarantees; after a write fails or times out, check its outcome before retrying.

Operator activation

Configure the Zild.Api environment:

McpServer__Enabled=true
McpServer__ApiBaseUrl=https://<zild-api-host>/
McpServer__RequestsPerMinute=60

ApiBaseUrl must point to the same API and end with /. Include any hosting prefix. The URL must represent the same protected resource and authentication audience. See Zild API for operation contracts.