Name: building-mcp-servers
Author: celigo

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 and, optionally, prompt templates, Celigo Storage files, and tools relayed from another MCP server. Concerns when building an MCP server: Endpoint identity unique relativeURI that, with the account's MCP alias, forms the server's URL 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) Prompts, files and proxies inline prompt templates ( prompts[] ), Celigo Storage files ( resources[] ), and an upstream MCP server's capabilities ( upstreamMcpConnections[] ) Annotations MCP standard behavior hints ( readOnlyHint , destructiveHint , idempotentHint , openWorldHint ) that help AI agents decide when and how to call a tool Overrides per server connection bindings for a tool's steps. Every tool entry needs one for each step, and they're the only overrides that change what a call does 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 recommended choice, which you must turn on explicitly with oauth: {useCeligoOauth: true} ), an external IdP, or static API tokens, gated by mcp:read / mcp:write scopes plus optional traffic limits and an IP network policy (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 A server publishes four kinds of entries, and can relay another MCP server's capabilities: 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 need overrides that bind each of the Tool's steps to a connection for this server. 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. Prompt Entries ( prompts[] ) Prompt templates defined inline on the server there's no separate prompt resource. Each has a name (letters, digits, , , . ; unique among the server's prompts, though it may match a tool's name), one or more messagesTemplate[] messages with role user or assistant ( system is refused), and arguments[] declaring each {{placeholder}} the templates use (argument names: letters, digits and ). Clients list them with prompts/list and fetch them rendered with prompts/get . Unlike every other entry, a prompt sent without disabled is saved enabled . A prompt keeps its id the handle prompt:< id grants name only while its name stays the same: a renamed prompt gets a new id , and grants on the old one stop matching it. Resource Entries ( resources[] ) Celigo Storage files served to clients ( resources/list , resources/read ), each named by fileId with an optional title . The file must be an active file in this account, not a folder, and can appear once per server; sandbox servers can't have resources. Resource entries start disabled. An entry keeps its id (the resource:< id grant handle) only while it points at the same file. Uploading files and reading their status: [managing file storage 3. Upload a file or create a folder](../managing file storage/SKILL.md 3 upload a file or create a folder). Proxied MCP Servers ( upstreamMcpConnections[] ) To give clients a vendor's own MCP tools, attach the vendor's MCP connection (a Connection of type: "mcp" ) and whitelist what to relay. Each attachment lists rows by the upstream's own names tools[] , prompts[] and resources[] , each row {"upstreamName": ...} with optional presentation overrides at most 500 rows per attachment, and only listed rows are served, under this server's URL, sign in and grants. The upstream is always called with the connection's own credentials, whoever the caller is. Discovery, which reads the upstream's catalog and flags rows that changed or disappeared, runs from the integrator.io UI. The attachment's alias (letters, digits, , ; at most 32 characters; stored lowercase) is derived from the connection's name when you omit it, so set it when that name is longer. A full update that omits upstreamMcpConnections keeps it, but one that includes it approves the upstream's current definitions, including any that changed since they were last approved and so does celigo mcp servers set on any field it can't patch, because it sends the whole document. Typical Compositions Publish an existing builder API as it is; build a new capability as a Tool, which gets annotations and per server connection bindings. One server can mix every kind above. 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 , disabled: false , and a binding for each of the Tool's steps (see [step 6]( 6 configure overrides tool entries only)) Each API entry needs: apiId , name , disabled: false Each prompt needs name and at least one messagesTemplate[] message; each resource needs fileId . Tool, API and resource entries default to disabled: true a prompt sent without disabled is saved enabled and clients never see a disabled entry. Schema Index The schemas are in [references/schemas/](references/schemas/), and the fields every response shares in [references/common schemas/](references/common schemas/): Schema What it defines [request.yml](references/schemas/request.yml) Top level MCP server fields (name, relativeURI, description, disabled, tools, apis) [base.yml](references/schemas/base.yml) Every writable server field, and which ones a full update clears or keeps when omitted [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) [prompt.yml](references/schemas/prompt.yml) Prompt entry (name, arguments, messagesTemplate, disabled) [resource.yml](references/schemas/resource.yml) Resource entry (a Celigo Storage fileId , title, disabled) [upstream mcp connection.yml](references/schemas/upstream mcp connection.yml) Proxied MCP server attachment and its whitelisted rows [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 [server connection.yml](references/schemas/server connection.yml) A connections[] entry and its requiresEndUserCredentials flag [permission set.yml](references/schemas/permission set.yml) Capability set ( permissionSets[] ) [oauth config.yml](references/schemas/oauth config.yml) The oauth block's three sign in modes [policy.yml](references/schemas/policy.yml) A traffic limit ( policies[] ): rate limit or quota [resource response.yml](references/common schemas/resource response.yml) id , createdAt , lastModified and deletedAt , shared by every resource response 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 [managing network policies Where a Policy Applies](../managing network policies/SKILL.md where a policy applies) limit which networks can reach the server with an IP allow/deny list ( networkPolicyId ) [managing end users How Access Composes](../managing end users/SKILL.md how access composes) who may call a Celigo OAuth server: end users, groups, roles and capability sets [managing api tokens Where Tokens Are Managed](../managing api tokens/SKILL.md where tokens are managed) the API tokens automation uses to call the server [managing file storage Which Operation](../managing file storage/SKILL.md which operation) the Celigo Storage files a server publishes as resources <! 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 . If the goal is an AI assistant that works on the Celigo account itself its flows, errors and builds don't build a server: connect the assistant to the Celigo Platform MCP server, which Celigo hosts in each region ([Connect the Celigo MCP server](https://github.com/celigo/ai/blob/main/docs/connect mcp.md)). Build a server to give outside clients your own business capabilities. 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 ) An entry has no description of its own. Clients get the Tool's own description verbatim as the tool's description, its name as the tool's title , and its input and output schemas as inputSchema and outputSchema ; an API en