building-mcp-servers

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Building MCP Servers

构建MCP服务器

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.

MCP服务器是一种模型上下文协议（Model Context Protocol）端点，它将Celigo工具（Tools）和构建器模式API（builder-mode APIs）作为可调用工具暴露给外部AI Agent和MCP客户端。构建MCP服务器时需要关注以下要点：

端点标识——唯一的
```
relativeURI
```
，构成服务器的URL路径
工具选择——要暴露哪些工具资源，每个工具需具备符合MCP规范的名称
API选择——要暴露哪些构建器模式API资源（不支持脚本模式API）
注解——MCP标准行为提示（
```
readOnlyHint
```
、
```
destructiveHint
```
、
```
idempotentHint
```
、
```
openWorldHint
```
），帮助AI Agent决定何时以及如何调用工具
覆盖项——在不修改底层工具定义的前提下，针对单个服务器自定义工具的连接、导出、导入和路由配置
名称唯一性——服务器内所有
```
tools[]
```
和
```
apis[]
```
条目中的工具名称必须唯一

MCP服务器支持可配置的身份验证——默认是Celigo OAuth，也支持外部身份提供商（IdP）或静态API令牌，权限由

mcp:read

mcp:write

范围控制（详见身份验证与权限范围）。对外部系统的出站调用使用底层工具和API引用的连接。

MCP服务器与工具和API配合使用，是一个轻量的暴露层——所有处理逻辑都存在于被引用的工具和API资源中。

Composition Patterns

组合模式

MCP servers combine two types of entries:

MCP服务器包含两种类型的条目：

Tool Entries (

tools[]

)

工具条目（

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

引用Celigo工具资源。每个工具会成为一个MCP工具端点。工具的

input.schema

根节点必须为

type: "object"

，以符合MCP规范。工具条目支持注解（行为提示）和覆盖项（针对单个服务器的连接/资源自定义）。

API Entries (

apis[]

)

API条目（

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.

引用Celigo构建器模式API资源。每个API会成为一个MCP工具端点。仅支持

type: "builder"

类型的API——脚本模式和遗留API无法通过MCP暴露。API条目不支持注解或覆盖项。

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

生产环境中，大多数MCP服务器仅暴露API。同时包含工具和API的服务器较为少见，但在混合读写场景下是有效的（例如，使用带注解的工具执行写入操作，使用API进行查询）。

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

你需要...	使用工具条目	使用API条目
暴露具备连接灵活性的可复用逻辑	是	--
向AI Agent提示行为（只读、破坏性）	是（注解）	--
在不修改资源的前提下，针对单个服务器切换连接	是（覆盖项）	--
将构建器模式API暴露为MCP端点	--	是
暴露脚本模式或遗留API	不支持	不支持

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

每个MCP服务器至少需要：

```
name
```
——人类可读的标签
```
relativeURI
```
——唯一的URI路径段（必须以
```
/
```
开头，单个路径段，仅包含字母数字、下划线和连字符）

每个工具条目需要：

_toolId

、

name

每个API条目需要：

_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

所有架构都位于references/schemas/：

架构	定义内容
request.yml	MCP服务器顶层字段（name、relativeURI、description、disabled、tools、apis）
response.yml	MCP服务器响应结构（包含_id、时间戳、沙箱）
io-tool.yml	工具条目架构（_toolId、name、disabled、annotations、overrides）
api-tool.yml	API条目架构（_apiId、name、disabled）
annotations.yml	MCP行为提示（title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint）
overrides.yml	针对单个服务器的连接、导出、导入和路由覆盖项

Related Skills

How to Build an MCP Server

如何构建MCP服务器

1. Plan what the server exposes

1. 规划服务器暴露的功能

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

在创建任何资源之前，确定MCP服务器应为AI Agent提供哪些功能。每个功能对应一个工具或构建器模式API。将相关功能分组到单个服务器下，并设置有意义的

relativeURI

。

2. Check for existing resources

2. 检查现有资源

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

bash

undefined

在创建新资源之前，先寻找可复用的工具和API。

bash

undefined

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)

检查现有API（仅构建器模式可使用）

celigo apis list

Check existing MCP servers for patterns

检查现有MCP服务器的模式

celigo mcp-servers list

undefined

celigo mcp-servers list

undefined

3. Build the underlying resources (bottom-up)

3. 构建底层资源（自底向上）

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

MCP服务器引用工具和API——这些资源必须先存在。构建顺序：

连接——创建或复用与目标系统的连接
导出项 + 导入项——工具/API流水线的数据源和目标
工具——可复用逻辑块（使用
```
building-tools
```
技能）。确保
```
input.schema
```
根节点为
```
type: "object"
```
以兼容MCP
API——构建器模式端点（使用
```
building-apis
```
技能）。确保设置了
```
type: "builder"
```
MCP服务器——引用工具和API的暴露层

4. Choose tool names

4. 选择工具名称

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

每个条目（工具或API）需要一个

name

，该名称会成为AI Agent可见的MCP工具名称。名称必须：

在服务器的所有
```
tools[]
```
和
```
apis[]
```
条目中唯一
仅包含字母数字、下划线、连字符和点
足够描述性，以便AI Agent理解工具的用途（例如：
```
get_customer
```
、
```
create_order
```
、
```
validate.input
```
）

5. Configure annotations (tool entries only)

5. 配置注解（仅工具条目）

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.

注解是可选的MCP标准提示，帮助AI Agent决定何时以及如何调用工具。根据底层工具的实际功能设置：

```
readOnlyHint: true
```
——工具仅读取数据，无副作用（例如查询）
```
destructiveHint: true
```
——工具删除或永久修改数据
```
idempotentHint: true
```
——使用相同输入多次调用会产生相同结果
```
openWorldHint: true
```
——工具与外部API交互，调用结果可能因调用次数而异

注解仅为提示——服务器不会强制执行。

6. Configure overrides (tool entries only)

6. 配置覆盖项（仅工具条目）

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.

覆盖项允许你针对此特定MCP服务器自定义工具的内部资源，而无需修改工具定义。这使得同一工具可在多个服务器中复用，且配置不同。

最常见的覆盖项是连接覆盖——将工具的抽象连接引用映射到此服务器使用的具体连接。覆盖条目使用

_abstractId

（工具定义中的连接ID）和

_id

（替代使用的具体连接ID）。

导出项、导入项和路由覆盖也可用，但实际中很少使用。

7. Build the MCP server JSON

7. 构建MCP服务器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).

参考架构索引获取确切的字段架构。每个MCP服务器至少需要：

name

和

relativeURI

。添加

tools[]

和/或

apis[]

条目以暴露功能。设置

disabled: false

以启用服务器（至少一个工具或API条目也必须启用）。

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

决定谁可以调用服务器是确定服务器暴露内容后的第二个设计决策。MCP服务器有自己的可配置身份验证，独立于底层工具使用的连接。Celigo OAuth和API令牌可在同一服务器上同时启用——这是服务器同时服务人类用户（OAuth）和自动化程序（令牌）时的常见配置。

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.

Celigo OAuth——每个新服务器的默认身份提供商。消费者使用其Celigo凭据进行身份验证（如果账户配置了SSO，会自动路由到你的SSO提供商）。仅此模式支持按用户下游连接（每个调用者使用自己的Celigo连接），以及服务器访问选项卡上的显式用户列表。
外部IdP（外部OAuth）——验证由你的身份提供商（Auth0、Okta等）颁发的OAuth令牌。外部提供商在账户级别配置一次，可被任何服务器引用；服务器存储颁发者URL、受众、验证方法（JWKS或内省）和所需权限范围（
```
mcp:read
```
、
```
mcp:write
```
或两者）。使用外部IdP时，不会显示用户列表，也不支持按用户下游连接。需先检查提供商限制：Auth0要求其应用启用资源参数兼容配置文件，且Microsoft Entra ID和Google Identity目前不支持MCP OAuth。
API令牌——消费者在每次请求中发送的静态Bearer令牌。在服务器上创建（也会出现在账户的全局API令牌列表中），包含名称、可选描述和自动清除窗口；令牌值仅在创建时显示一次。适用于服务间调用者、无法使用OAuth的遗留客户端、短期访问，或作为OAuth的备用方案。API令牌本身没有权限范围缩小的UI——其粒度来自服务器的工具列表和
```
mcp:read
```
/
```
mcp:write
```
的划分。

默认使用Celigo OAuth，当需要支持自动化时，可同时添加API令牌。仅当消费者明确要求特定提供商时，才使用外部IdP。

Scopes --

mcp:read

mcp:write

权限范围——

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.

每个OAuth路径（Celigo或外部）要求颁发的令牌携带MCP权限范围：

mcp:read
——非破坏性操作，例如列出可用工具（
```
tools/list
```
）和调用无副作用的底层工具或API。
mcp:write
——可能更改数据或状态的操作。

每次请求都会检查权限范围；结构有效但缺少所需权限范围的令牌会被拒绝。授予消费者所需的最小权限范围——只读合作伙伴不应获得

mcp:write

。权限范围声明通常位于标准OAuth的

scope

或

scp

声明中，具体取决于IdP。

CLI Commands

CLI命令

bash

undefined

bash

undefined

CRUD

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


<!-- TIER:3 -->

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


<!-- 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

在创建或更新MCP服务器之前，验证以下内容：

设置了
```
name
```
且描述性强
```
relativeURI
```
以
```
/
```
开头，包含单个路径段，仅使用字母数字、下划线和连字符
```
relativeURI
```
在账户的所有MCP服务器中唯一
```
tools[]
```
中的所有
```
_toolId
```
引用指向现有工具资源
```
apis[]
```
中的所有
```
_apiId
```
引用指向现有构建器模式API资源（非脚本模式或遗留API）
服务器内所有
```
tools[]
```
和
```
apis[]
```
条目中的工具名称唯一
工具名称仅包含字母数字、下划线、连字符和点
引用工具的工具条目验证工具的
```
input.schema
```
根节点为
```
type: "object"
```
如果服务器已启用（
```
disabled: false
```
），则至少有一个工具或API条目已启用（
```
disabled: false
```
）
连接覆盖项（如果使用）将
```
_abstractId
```
映射到有效的具体连接ID
沙箱MCP服务器仅引用沙箱连接和资源

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.

PUT请求会删除未包含的字段。始终先执行GET请求，修改后再执行PUT请求。
```
set
```
命令会自动处理此问题。
无法暴露脚本模式和遗留API。仅
```
type: "builder"
```
类型的API可在MCP服务器中使用。如果API条目出现验证错误，请确认引用的API设置了
```
type: "builder"
```
。
工具输入架构必须为
type: "object"
。MCP规范要求工具输入为JSON对象。如果工具的
```
input.schema
```
根节点类型不同（例如
```
array
```
、
```
string
```
），则无法通过MCP暴露。
注解仅为提示，不强制执行。设置
```
readOnlyHint: true
```
不会阻止工具写入数据。AI Agent可能完全忽略注解。
名称唯一性覆盖两个数组。
```
tools[]
```
中名为
```
get_customer
```
的工具与
```
apis[]
```
中同样名为
```
get_customer
```
的API冲突。名称在合并后的集合中必须唯一。
覆盖项仅适用于工具条目。
```
apis[]
```
中的API条目不支持注解或覆盖项。要针对单个服务器自定义API行为，需修改API资源本身。
启用服务器需要至少一个已启用的条目。仅设置服务器的
```
disabled: false
```
是不够的——服务器内至少有一个工具或API必须设置
```
disabled: false
```
。
预览和日志端点仅支持会话身份验证。MCP服务器的
```
/preview
```
和
```
/logs
```
端点无法通过Bearer令牌访问——它们需要UI会话。
MCP服务器和MCP连接是相反的概念。MCP服务器（本资源）向外发布你的功能，供外部MCP客户端调用。MCP连接是一个单独的连接资源（
```
type: "mcp"
```
），用于消费外部MCP服务器，即Celigo向外调用。它们共享"MCP"一词，但配置位置不同——混淆两者是常见错误。如果目标是将Celigo连接到外部MCP服务器，请使用MCP连接，而非本资源。
每次调用都算作一次MCP调用。每个工具或API调用都会计入账户的MCP使用额度，包括失败的调用——500错误仍会消耗一次调用——使用情况会在账户的所有MCP服务器中汇总。使用限制是软性的（阈值通知，而非阻止），因此消费者端的重试会增加使用量。

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`

错误	原因	修复方法
创建/更新时出现422错误	缺少必填字段或 `relativeURI` 格式无效	检查 `name` 和 `relativeURI` ；确保URI以 `/` 开头且为有效单个路径段
422错误 `_toolId not found`	引用的工具不存在或已被删除	使用 `celigo tools get <id>` 验证工具是否存在
422错误 `_apiId not found`	引用的API不存在或已被删除	使用 `celigo apis get <id>` 验证API是否存在
422错误 `duplicate tool name`	两个条目名称相同	确保 `tools[]` 和 `apis[]` 中的所有名称唯一
422错误 `relativeURI already in use`	账户中另一个MCP服务器使用了相同的URI	选择不同的 `relativeURI` ；使用 `celigo mcp-servers list` 检查
422错误 `invalid API type`	API条目引用了脚本模式或遗留API	仅支持 `type: "builder"` 类型的API；使用 `celigo apis get <id>` 检查
422错误 `input schema invalid`	工具的 `input.schema` 根节点类型不是 `object`	更新工具的输入架构，使其根节点为 `type: "object"`
服务器已启用但无法访问	所有工具/API条目都已禁用	启用至少一个条目，设置 `disabled: false`

building-mcp-servers

Original

Translation

Building MCP Servers

构建MCP服务器

Composition Patterns

组合模式

Tool Entries (tools[])

工具条目（tools[]）

API Entries (apis[])

API条目（apis[]）

Typical Compositions

典型组合

Quick Reference

快速参考

Decision Matrix

决策矩阵

Minimum Required Fields

必填字段

Schema Index

架构索引

Related Skills

相关技能

How to Build an MCP Server

如何构建MCP服务器

1. Plan what the server exposes

1. 规划服务器暴露的功能

2. Check for existing resources

2. 检查现有资源

Search across all resource types in the account

在账户中搜索所有资源类型

Check existing tools

检查现有工具

Check existing APIs (only builder-mode can be used)

检查现有API（仅构建器模式可使用）

Check existing MCP servers for patterns

检查现有MCP服务器的模式

3. Build the underlying resources (bottom-up)

3. 构建底层资源（自底向上）

4. Choose tool names

4. 选择工具名称

5. Configure annotations (tool entries only)

5. 配置注解（仅工具条目）

6. Configure overrides (tool entries only)

6. 配置覆盖项（仅工具条目）

7. Build the MCP server JSON

7. 构建MCP服务器JSON

Authentication and Scoping

身份验证与权限范围

Authentication modes

身份验证模式

Scopes -- mcp:read vs mcp:write

权限范围——mcp:read vs mcp:write

CLI Commands

CLI命令

CRUD

CRUD操作

Discovery

发现资源

Pre-Submit Checklist

提交前检查清单

Gotchas

注意事项

Common Errors

常见错误

Tool Entries (
`tools[]`
)

工具条目（
`tools[]`
）

API Entries (
`apis[]`
)

API条目（
`apis[]`
）

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

权限范围——
`mcp:read`
vs
`mcp:write`