Building MCP Servers

<!-- TIER:1 -->

Building MCP Servers

An MCP server is a Model Context Protocol endpoint that exposes Celigo Tools and builder-mode APIs as callable tools for external AI agents and MCP clients. Concerns when building an MCP server:

• Endpoint identity -- unique relativeURI that forms the server's URL path
• Tool selection -- which Tool resources to expose, each with an MCP-compatible name
• API selection -- which builder-mode API resources to expose (script-mode APIs are not supported)
• Annotations -- MCP-standard behavior hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) that help AI agents decide when and how to call a tool
• Overrides -- per-server customization of a tool's connections, exports, imports, and routers without modifying the underlying tool definition
• Name uniqueness -- tool names must be unique across all tools[] and apis[] entries within the server

MCP servers support configurable authentication of their own -- Celigo OAuth (the default), an external IdP, or static API tokens, gated by mcp:read / mcp:write scopes (see Authentication and Scoping). Outbound calls to external systems use the connections referenced by the underlying tools and APIs.

Used alongside tools and APIs. The MCP server is a thin exposure layer -- all processing logic lives in the referenced Tool and API resources.

Composition Patterns

MCP servers combine two types of entries:

Tool Entries (tools[])

Reference Celigo Tool resources. Each tool becomes an MCP tool endpoint. The tool's input.schema must have type: "object" at the root to comply with the MCP specification. Tool entries support annotations (behavior hints) and overrides (per-server connection/resource customization).

API Entries (apis[])

Reference Celigo builder-mode API resources. Each API becomes an MCP tool endpoint. Only type: "builder" APIs are supported -- script-mode and legacy APIs cannot be exposed via MCP. API entries do not support annotations or overrides.

Typical Compositions

In production, most MCP servers expose APIs only. Servers that combine both tools and APIs are less common but valid for mixed read/write patterns (e.g., tools for writes with annotations, APIs for lookups).

Quick Reference

Decision Matrix

Minimum Required Fields

Every MCP server needs at minimum:

• name -- human-readable label
• relativeURI -- unique URI path segment (must start with /, single segment, alphanumeric + underscores + hyphens)

Each tool entry needs: _toolId, name

Each API entry needs: _apiId, name

Schema Index

All schemas are in references/schemas/:

Related Skills

• building-tools > How to Build a Tool -- building the Tool resources that MCP servers expose
• building-apis > How to Build an API -- building the builder-mode APIs that MCP servers expose
• configuring-connections > Quick Reference -- connections used by tools and overridden per-server
• configuring-exports > Quick Reference -- exports used as lookups within tool pipelines
• configuring-imports > Quick Reference -- imports used as action steps within tool pipelines

<!-- TIER:2 -->

How to Build an MCP Server

1. Plan what the server exposes

Before creating anything, determine what capabilities the MCP server should offer to AI agents. Each capability maps to either a Tool or a builder-mode API. Group related capabilities under a single server with a meaningful relativeURI.

2. Check for existing resources

Look for tools and APIs that can be reused before creating new ones.

# Search across all resource types in the account
celigo account search "<keyword>"

# Check existing tools
celigo tools list

# Check existing APIs (only builder-mode can be used)
celigo apis list

# Check existing MCP servers for patterns
celigo mcp-servers list

3. Build the underlying resources (bottom-up)

MCP servers reference tools and APIs -- these must exist first. Build order:

1. Connections -- create or reuse connections to target systems
2. Exports + Imports -- data sources and destinations for tool/API pipelines
3. Tools -- reusable logic blocks (use building-tools skill). Ensure input.schema has type: "object" at root for MCP compatibility
4. APIs -- builder-mode endpoints (use building-apis skill). Ensure type: "builder" is set
5. MCP Server -- the exposure layer that references tools and APIs

4. Choose tool names

Each entry (tool or API) needs a name that becomes the MCP tool name visible to AI agents. Names must:

• Be unique across all tools[] and apis[] entries in the server
• Contain only alphanumeric characters, underscores, hyphens, and dots
• Be descriptive enough for an AI agent to understand the tool's purpose (e.g., get_customer, create_order, validate.input)

5. Configure annotations (tool entries only)

Annotations are optional MCP-standard hints that help AI agents decide when and how to call a tool. Set them based on what the underlying tool actually does:

• readOnlyHint: true -- tool only reads data, no side effects (e.g., a lookup)
• destructiveHint: true -- tool deletes or permanently modifies data
• idempotentHint: true -- calling multiple times with the same input produces the same result
• openWorldHint: true -- tool interacts with external APIs where results may vary between calls

Annotations are hints only -- they are not enforced by the server.

6. Configure overrides (tool entries only)

Overrides let you customize a tool's internal resources for this specific MCP server without modifying the tool definition. This enables reusing the same tool across multiple servers with different configurations.

The most common override is connection overrides -- mapping the tool's abstract connection references to concrete connections for this server. Override entries use _abstractId (the connection ID in the tool definition) and _id (the concrete connection to use instead).

Export, import, and router overrides are also available but rarely used in practice.

7. Build the MCP server JSON

Reference the Schema Index for exact field schemas. Every MCP server needs at minimum: name and relativeURI. Add tools[] and/or apis[] entries to expose capabilities. Set disabled: false to enable the server (at least one tool or API entry must also be enabled).