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

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/:

Schema	What it defines
request.yml	Top-level MCP server fields (name, relativeURI, description, disabled, tools, apis)
response.yml	MCP server response shape (includes _id, timestamps, sandbox)
io-tool.yml	Tool entry schema (_toolId, name, disabled, annotations, overrides)
api-tool.yml	API entry schema (_apiId, name, disabled)
annotations.yml	MCP behavior hints (title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
overrides.yml	Per-server overrides for connections, exports, imports, and routers

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.

bash

# 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:

Connections -- create or reuse connections to target systems
Exports + Imports -- data sources and destinations for tool/API pipelines
Tools -- reusable logic blocks (use
```
building-tools
```
skill). Ensure
```
input.schema
```
has
```
type: "object"
```
at root for MCP compatibility
APIs -- builder-mode endpoints (use
```
building-apis
```
skill). Ensure
```
type: "builder"
```
is set
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

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

scp

claim, depending on the IdP.

CLI Commands

bash

# CRUD
celigo mcp-servers list
celigo mcp-servers get <id>
celigo mcp-servers create < mcp-server.json
celigo mcp-servers update <id> < mcp-server.json
celigo mcp-servers set <id> key=value [key2=value2 ...]
celigo mcp-servers delete <id>

# Discovery
celigo account search "<keyword>"
celigo tools list
celigo apis list

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

PUT erases omitted fields. Always GET first, modify, then PUT. The
```
set
```
command handles this automatically.
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.
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.
Annotations are hints, not enforcement. Setting
```
readOnlyHint: true
```
does not prevent the tool from writing data. The AI agent may ignore annotations entirely.
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.
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.
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
```
.
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.
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.
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

Error	Cause	Fix
422 on create/update	Missing required fields or invalid `relativeURI` format	Check `name` and `relativeURI` ; ensure URI starts with `/` and is a single valid segment
422 `_toolId not found`	Referenced tool does not exist or was deleted	Verify the tool exists with `celigo tools get <id>`
422 `_apiId not found`	Referenced API does not exist or was deleted	Verify the API exists with `celigo apis get <id>`
422 `duplicate tool name`	Two entries share the same `name`	Ensure all names across `tools[]` and `apis[]` are unique
422 `relativeURI already in use`	Another MCP server in the account uses the same URI	Choose a different `relativeURI` ; check with `celigo mcp-servers list`
422 `invalid API type`	API entry references a script-mode or legacy API	Only `type: "builder"` APIs are supported; check with `celigo apis get <id>`
422 `input schema invalid`	Tool's `input.schema` root type is not `object`	Update the tool's input schema to have `type: "object"` at root
Server enabled but not accessible	All tool/API entries are disabled	Enable at least one entry with `disabled: false`

building-mcp-servers

NPX Install

Tags

SKILL.md Content

Building MCP Servers

Composition Patterns

Tool Entries (
`tools[]`
)

API Entries (
`apis[]`
)

Typical Compositions

Quick Reference

Decision Matrix

Minimum Required Fields

Schema Index

Related Skills

How to Build an MCP Server

1. Plan what the server exposes

2. Check for existing resources

3. Build the underlying resources (bottom-up)

4. Choose tool names

5. Configure annotations (tool entries only)

6. Configure overrides (tool entries only)

7. Build the MCP server JSON

Authentication and Scoping

Authentication modes

Scopes --
`mcp:read`
vs
`mcp:write`

CLI Commands

Pre-Submit Checklist

Gotchas

Common Errors

building-mcp-servers

NPX Install

Tags

SKILL.md Content

Building MCP Servers

Composition Patterns

Tool Entries (tools[])

API Entries (apis[])

Typical Compositions

Quick Reference

Decision Matrix

Minimum Required Fields

Schema Index

Related Skills

How to Build an MCP Server

1. Plan what the server exposes

2. Check for existing resources

3. Build the underlying resources (bottom-up)

4. Choose tool names

5. Configure annotations (tool entries only)

6. Configure overrides (tool entries only)

7. Build the MCP server JSON

Authentication and Scoping

Authentication modes

Scopes -- mcp:read vs mcp:write

CLI Commands

Pre-Submit Checklist

Gotchas

Common Errors

Tool Entries (
`tools[]`
)

API Entries (
`apis[]`
)

Scopes --
`mcp:read`
vs
`mcp:write`