Build Celigo MCP server resources -- endpoints that expose Tools and builder-mode APIs to external AI agents and MCP clients. Use when creating MCP servers, linking tools or APIs, or configuring annotations and overrides.

<! 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]( 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 You need to... Use tool entry Use API entry Expose reusable logic with connection flexibility Yes Hint behavior to AI agents (read only, destructive) Yes (annotations) Swap connections per server without modifying the resource Yes (overrides) Expose a builder mode API as an MCP endpoint Yes Expose a script mode or legacy API Not supported Not supported 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/](references/schemas/): Schema What it defines [request.yml](references/schemas/request.yml) Top level MCP server fields (name, relativeURI, description, disabled, tools, apis) [response.yml](references/schemas/response.yml) MCP server response shape (includes id, timestamps, sandbox) [io tool.yml](references/schemas/io tool.yml) Tool entry schema ( toolId, name, disabled, annotations, overrides) [api tool.yml](references/schemas/api tool.yml) API entry schema ( apiId, name, disabled) [annotations.yml](references/schemas/annotations.yml) MCP behavior hints (title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint) [overrides.yml](references/schemas/overrides.yml) Per server overrides for connections, exports, imports, and routers Related Skills [building tools How to Build a Tool](../building tools/SKILL.md how to build a tool) building the Tool resources that MCP servers expose [building apis How to Build an API](../building apis/SKILL.md how to build an api) building the builder mode APIs that MCP servers expose [configuring connections Quick Reference](../configuring connections/SKILL.md quick reference) connections used by tools and overridden per server [configuring exports Quick Reference](../configuring exports/SKILL.md quick reference) exports used as lookups within tool pipelines [configuring imports Quick Reference](../configuring imports/SKILL.md 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. 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]( 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 <! TIER:3 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.

building-mcp-servers