由 ACI.dev 提供支持的 MCP 服务器

有关 MCP 服务器的完整文档和教程，请访问 aci.dev 文档.

目录

• 由 ACI.dev 提供支持的 MCP 服务器
  • 目录
  • 概述
  • 先决条件
  • 安装
  • 使用方法
    • Apps 服务器
    • 统一服务器
  • 理解两种服务器类型
    • Apps 服务器
    • 统一服务器
  • 配置
    • 与 Claude 桌面一起使用
    • 与 Cursor 一起使用
  • 常见问题解答
  • 调试

概述

有关 MCP 服务器的完整文档和教程，请访问 aci.dev 文档.

此包提供了两个 Model Context Protocol (MCP) 服务器，用于访问 ACI.dev 管理的功能（工具）：

• aci-mcp-apps：一个 MCP 服务器，提供对指定应用中的功能（工具）的直接访问
• aci-mcp-unified：一个 MCP 服务器，提供了两个元功能（工具）（ACI_SEARCH_FUNCTIONS_WITH_INTENT 和 ACI_EXECUTE_FUNCTION），以发现并执行 ACI.dev 上可用的所有功能（工具）

先决条件

在使用此包之前，您需要（更多信息请参见 教程）：

1. 设置 ACI_API_KEY 环境变量，使用您的 ACI.dev API 密钥
2. 在 platform.aci.dev 上为您的代理配置应用程序并将它们设置在 allowed_apps 中。
3. 将特定于应用程序的帐户链接到相同的 --linked-account-owner-id，稍后将使用它来启动 MCP 服务器。

安装

该包已发布到 PyPI，因此您可以直接使用 uvx 运行它：

# Install uv if you don't have it already
curl -sSf https://install.pypa.io/get-pip.py | python3 -
pip install uv

使用方法

Apps 服务器

Apps 服务器提供对特定应用程序下的功能（工具）的直接访问。
您可以使用 --apps 参数指定一个或多个应用程序。（有关可用应用程序的列表，请访问 ACI.dev）

# Using stdio transport (default)
uvx aci-mcp apps-server --apps "BRAVE_SEARCH,GMAIL" --linked-account-owner-id <LINKED_ACCOUNT_OWNER_ID>

# Using SSE transport with custom port
uvx aci-mcp apps-server --apps "BRAVE_SEARCH,GMAIL" --linked-account-owner-id <LINKED_ACCOUNT_OWNER_ID> --transport sse --port 8000

统一服务器

统一服务器提供了两个元功能（工具），用于发现和执行 ACI.dev 上可用的任何功能（工具），即使这些功能未直接列在服务器中。

根据您的意图/需求动态搜索和执行功能（工具）。您无需担心成千上万的工具占用 LLM 的上下文窗口或集成多个 MCP 服务器。

# During functions (tools) search/discovery, allow discoverability of all functions (tools) available on ACI.dev
uvx aci-mcp unified-server --linked-account-owner-id <LINKED_ACCOUNT_OWNER_ID>

# During functions (tools) search/discovery, limit to only functions (tools) accessible by the requesting agent (identified by ACI_API_KEY)
uvx aci-mcp unified-server --linked-account-owner-id <LINKED_ACCOUNT_OWNER_ID> --allowed-apps-only

理解两种服务器类型

有关 MCP 服务器的完整文档和教程，请访问 aci.dev 文档.

Apps 服务器

应用程序服务器通过 --apps 参数提供了对特定应用程序功能/工具的直接访问。当MCP客户端（例如Claude Desktop、Cursor等）与此服务器交互时，这些工具将直接出现在工具列表中。

统一服务器

统一服务器并不直接暴露特定于应用的工具。相反，它提供两个元功能（工具）：

1. ACI_SEARCH_FUNCTIONS_WITH_INTENT：根据您的意图/需求发现功能（工具）
2. ACI_EXECUTE_FUNCTION：执行由搜索发现的任何功能（工具）

这种方法允许MCP客户端动态地发现并使用ACI.dev平台上可用的任何功能，而无需事先列出所有功能。它可以根据您的需要搜索正确的工具，然后执行该工具。

配置

有关MCP服务器的完整文档和教程，请访问aci.dev 文档.

与Claude Desktop一起使用

在您的 claude_desktop_config.json 中添加以下内容：

{
  "mcpServers": {
    "aci-mcp-unified": {
      "command": "uvx",
      "args": ["aci-mcp", "unified-server", "--linked-account-owner-id", "<LINKED_ACCOUNT_OWNER_ID>"]
    }
  }
}

对于特定应用程序访问：

{
  "mcpServers": {
    "aci-mcp-apps": {
      "command": "uvx",
      "args": ["aci-mcp", "apps-server", "--apps", "BRAVE_SEARCH,GMAIL", "--linked-account-owner-id", "<LINKED_ACCOUNT_OWNER_ID>"]
    }
  }
}

与Cursor一起使用

在您的Cursor mcp.json 中添加以下内容：

{
    "mcpServers": {
      "aci-mcp-unified": {
        "command": "uvx",
        "args": ["aci-mcp", "unified-server", "--linked-account-owner-id", "<LINKED_ACCOUNT_OWNER_ID>"],
        "env": {
            "ACI_API_KEY": "<ACI_API_KEY>"
        }
      }
    }
  }

对于特定应用程序访问：

{
  "mcpServers": {
    "aci-mcp-apps": {
        "command": "uvx",
        "args": ["aci-mcp", "apps-server", "--apps", "BRAVE_SEARCH,GMAIL", "--linked-account-owner-id", "<LINKED_ACCOUNT_OWNER_ID>"],
        "env": {
            "ACI_API_KEY": "<ACI_API_KEY>"
        }
    }
  }
}

常见问题解答

• 如何获取 ACI_API_KEY？

  ACI_API_KEY 是您在 ACI.dev 项目中的 API 密钥。您可以在 ACI.dev 项目的设置中找到它。

• 如何配置应用程序并允许访问它们？

  您可以在 ACI.dev 项目的设置中配置应用程序并允许访问它们。

• 如何获取 LINKED_ACCOUNT_OWNER_ID？

  LINKED_ACCOUNT_OWNER_ID 是您希望用来访问功能的账户 ID。您可以在 ACI.dev 项目的设置中找到它。

• 使用统一服务器相比应用程序服务器有什么好处？

  目前大多数 MCP 服务器都限于特定的一组功能（工具），通常来自单一应用程序。如果您需要使用多个应用程序的功能，则需要集成多个 MCP 服务器。即使您可以接受集成多个 MCP 服务器的管理开销，您的 LLM 工具调用性能也可能受到影响，因为所有工具都会一次性加载到 LLM 的上下文窗口中。

  然而，统一服务器允许您动态地发现和执行 ACI.dev 上可用的任何功能，而不必担心成千上万的工具占用 LLM 的上下文窗口或不得不集成多个 MCP 服务器。

• 如何指定应用程序服务器要使用的应用程序列表？

  您可以使用 --apps 参数指定以逗号分隔的应用程序列表来使用应用程序服务器。尽量不要在应用程序名称之间留有空格。

• 我是否可以只使用一个应用程序中的功能（工具）？

  是的，您可以通过 --apps 参数指定（一个）应用程序名称，从而只使用一个应用程序中的功能（工具）。

调试

您可以使用 MCP 检查器来调试服务器：

# For unified server
npx @modelcontextprotocol/inspector uvx aci-mcp unified-server --linked-account-owner-id <LINKED_ACCOUNT_OWNER_ID>

# For apps server
npx @modelcontextprotocol/inspector uvx aci-mcp apps-server --apps "BRAVE_SEARCH,GMAIL" --linked-account-owner-id <LINKED_ACCOUNT_OWNER_ID>

运行 tail -n 20 -f ~/Library/Logs/Claude/mcp*.log 将显示来自服务器的日志，这可能有助于您调试任何问题。