---
title: "MCP 与工具协议"
description: "未来 MCP / 工具协议集成的现状与方向。"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.appaloft.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 与工具协议

## 标识 <a id="appaloft-mcp-server" />

Appaloft MCP Server 是可调用工具入口——它把既有的业务操作目录暴露给 MCP 客户端，**不会创建新的 AI-only 业务模型**。[完整 Appaloft Skill](/docs/agents/skill/)负责判断"该做什么"；MCP 负责在工具已配置时，精确执行"command/query 调用"这一步。

## 启动方式

```bash
# stdio 方式启动（大多数 Agent host 的默认接入方式）
appaloft mcp stdio

# 本地 HTTP JSON-RPC 端点，默认只绑定 localhost
appaloft mcp serve --host 127.0.0.1 --port 3939

# 独立 launcher，委托给同一套 Appaloft 运行时
npx appaloft-mcp
npx appaloft-mcp serve --host 127.0.0.1 --port 3939
```

启动 Server 本身**不会**部署应用、创建资源或修改任何状态——只有 MCP 客户端真正调用某个工具时，才会进入 Appaloft 的 command/query 总线。只有在可信反向代理或私有网络已提供安全边界时，才应该把 `--host` 从 `127.0.0.1` 改成其他值。

## 输入字段与校验：工具模型

每个工具都对应一个业务操作 key，命名规则是把 `.` 替换成 `_`：

| Operation key | Tool 名称 |
| --- | --- |
| `deployments.create` | `deployments_create` |
| `deployments.plan` | `deployments_plan` |
| `resources.configure-source` | `resources_configure_source` |
| `system.doctor` | `system_doctor` |

Tool 的输入 JSON Schema 直接来自和 CLI/API 相同的 Command/Query Schema；Command 调用会经过命令总线，Query 调用会经过查询总线，并标注 `entrypoint: "mcp"`，方便审计区分调用来源。

**不存在只有 Agent 才能调用的专属工具**。如果某个行为不在公开的业务操作目录里，它就不是合法的 Appaloft MCP 操作。

## 输出字段与状态值

Tool 描述会带 MCP 标注，标记查询是否只读、命令是否具有破坏性、查询是否幂等，以及部署类操作是否可能触达外部系统。响应会同时返回 JSON 文本和结构化内容，兼容旧版 MCP 客户端和支持结构化结果的新宿主。

### 只读资源

```text
appaloft://operation-catalog
appaloft://tools/high-value
appaloft://skill/appaloft
appaloft://skill/deploy-protocol
appaloft://tools/mcp-guide
appaloft://docs/agent
```

### Prompts

```text
appaloft-first-deploy
appaloft-recover-deployment
appaloft-configure-resource
appaloft-observe-runtime
appaloft-publish-static-artifact
```

Resources 和 Prompts 只提供上下文和工作流起点，**不拥有**写侧策略、租户选择、后台任务或隐藏状态。

## 错误码与安全边界

- 不绕过 Appaloft 直接调用仓库、Use Case、Provider SDK、Docker、SSH、代理或数据库。
- 不读取或输出 `.env`、私钥、Token、Cookie、数据库 URL、云厂商凭据或未脱敏日志。
- 鉴权、租户上下文、操作守卫、确认字段、密钥屏蔽和结构化错误都保留在既有运行时边界内，MCP 层不会绕过它们。
- 删除和破坏性操作仍然必须使用对应 Schema 中的删除安全检查和精确确认字段（例如要求输入完整 id 才能确认删除）。

## 和 Skill 的关系

当用户在支持 MCP 的 Agent Host 里说"帮我部署这个仓库"时，Host 会先加载[完整 Appaloft Skill](/docs/agents/skill/)判断意图，再根据当前会话是否配置了 Appaloft MCP，决定使用 MCP 工具调用、CLI、HTTP/API 还是 Web——四者最终都落到同一套业务操作。

## 示例

```bash
# 用 stdio 方式为本地 Agent host 提供 MCP 工具
appaloft mcp stdio
```

## 相关任务

- [完整 Appaloft Skill](/docs/agents/skill/)
- [Agent 部署子协议](/docs/agents/deploy-skill/)
- [选择入口](/docs/start/entrypoints/)

Source: https://docs.appaloft.com/agents/mcp/index.mdx