building-mcp-servers

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

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

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).

Authentication and Scoping

Deciding who can call a server is the second design decision after deciding what it exposes. MCP servers have their own configurable authentication, independent of the connections their underlying tools use. Celigo OAuth and API tokens can be enabled at the same time on one server -- a common shape when a server serves both human users (OAuth) and automation (tokens).

Authentication modes

• Celigo OAuth -- the default identity provider on every new server. Consumers authenticate with their Celigo credentials (routed to your SSO provider automatically if the account has SSO). Only this mode supports per-user downstream connections (each caller runs against their own Celigo connections) and an explicit Users list on the server's Access tab.
• External IdP (external OAuth) -- validates OAuth tokens issued by your own identity provider (Auth0, Okta, etc.). External providers are configured once at the account level and referenced from any server; the server stores the issuer URL, audience, validation method (JWKS or introspection), and required scopes (mcp:read, mcp:write, or both). With External, the Users list is not shown and per-user downstream connections are not available. Provider limits to check first: Auth0 requires the Resource Parameter Compatibility Profile on its application, and Microsoft Entra ID and Google Identity are not currently supported for MCP OAuth.
• API tokens -- static bearer tokens the consumer sends on every request. Created on the server (they also appear in the account's global API tokens list) with a name, optional description, and an auto-purge window; the token value is shown once at creation. Right for service-to-service callers, legacy clients that can't do OAuth, short-lived access, or as a fallback alongside OAuth. API tokens have no scope-narrowing UI of their own -- their granularity comes from the server's tool list and the mcp:read / mcp:write split.

Default to Celigo OAuth, and add an API token alongside it when automation is in scope. Reach for an external IdP only when the consumer explicitly requires a specific provider.

Scopes -- mcp:read vs mcp:write

Every OAuth path (Celigo or external) requires the issued token to carry MCP scopes:

• mcp:read -- non-destructive operations, such as listing available tools (tools/list) and invoking tools whose underlying Tool or API has no side effects.
• mcp:write -- operations that may change data or state.

The scope is checked on every request; a structurally valid token missing the required scope is rejected. Grant the minimum scope a consumer needs -- a read-only partner should not receive mcp:write. The scope claim usually lives in the standard OAuth scope or scp claim, depending on the IdP.

CLI Commands

Pre-Submit Checklist

Before creating or updating an MCP server, verify:

• name is set and descriptive
• relativeURI starts with /, contains a single path segment, uses only alphanumeric characters, underscores, and hyphens
• relativeURI is unique across all MCP servers in the account
• All _toolId references in tools[] point to existing Tool resources
• All _apiId references in apis[] point to existing builder-mode API resources (not script-mode or legacy)
• Tool names are unique across all tools[] and apis[] entries in the server
• Tool names contain only alphanumeric characters, underscores, hyphens, and dots
• Tool entries referencing Tools verify that the tool's input.schema has type: "object" at root
• At least one tool or API entry is enabled (disabled: false) if the server itself is enabled
• Connection overrides (if used) map _abstractId to valid concrete connection IDs
• Sandbox MCP servers only reference sandbox connections and resources

Gotchas

1. PUT erases omitted fields. Always GET first, modify, then PUT. The set command handles this automatically.
2. Script-mode and legacy APIs cannot be exposed. Only type: "builder" APIs work in MCP servers. If you get a validation error on an API entry, verify the referenced API has type: "builder" set.
3. Tool input schema must be type: "object". The MCP specification requires tool inputs to be JSON objects. If a tool's input.schema has a different root type (e.g., array, string), it cannot be exposed via MCP.
4. Annotations are hints, not enforcement. Setting readOnlyHint: true does not prevent the tool from writing data. The AI agent may ignore annotations entirely.
5. Name uniqueness spans both arrays. A tool named get_customer in tools[] conflicts with an API also named get_customer in apis[]. Names must be unique across the combined set.
6. Overrides only apply to tool entries. API entries in apis[] do not support annotations or overrides. To customize an API's behavior per-server, modify the API resource itself.
7. Enabling the server requires at least one enabled entry. Setting disabled: false on the server alone is not sufficient -- at least one tool or API within it must also have disabled: false.
8. Preview and logs endpoints are session-auth only. The /preview and /logs endpoints for MCP servers are not accessible via bearer token -- they require the UI session.
9. MCP server and MCP connection are opposite things. An MCP server (this resource) publishes your capabilities outward, so external MCP clients call in. An MCP connection is a separate Connection resource (type: "mcp") that consumes an external MCP server, so Celigo calls out. They share the word "MCP" and are configured in different places -- confusing the two is a common mistake here. If the goal is to wire Celigo to consume someone else's MCP server, reach for an MCP connection, not this resource.
10. Every invocation counts as one MCP call. Each tool or API invocation counts against the account's MCP entitlement, including failed calls -- a 500 still consumes a call -- and usage is aggregated across all MCP servers in the account. Enforcement is soft (threshold notifications, not blocking), so aggressive consumer-side retries inflate usage.

Common Errors