ACI Model Context Protocol (MCP) Servers

This package provides Model Context Protocol (MCP) servers that allow AI clients to access functions (tools) managed by ACI.dev. There are two primary server modes available:

1. aci-mcp-apps (apps-server): Provides direct access to functions (tools) from specific, user-defined apps.
2. aci-mcp-unified (unified-server): Provides meta-functions (ACI_SEARCH_FUNCTIONS and ACI_EXECUTE_FUNCTION) to discover and execute all functions available on the ACI.dev platform.

You can run the MCP servers in isolated Docker containers. Both server modes require the ACI_API_KEY environment variable and a --linked-account-owner-id flag.

Unified Server

Run the unified server to access all available ACI functions.

Apps Server

Run the apps server by specifying a comma-separated list of apps using the --apps flag.

Note: Ensure you replace <ACI_API_KEY> and <LINKED_ACCOUNT_OWNER_ID> with your actual credentials.

# Build the image
docker build -t aci-mcp .

# Run the unified server
docker run --rm -i -e ACI_API_KEY=<ACI_API_KEY> aci-mcp unified-server --linked-account-owner-id <LINKED_ACCOUNT_OWNER_ID>

# Run the apps server
docker run --rm -i -e ACI_API_KEY=<ACI_API_KEY> aci-mcp apps-server --apps <APP1,APP2,...> --linked-account-owner-id <LINKED_ACCOUNT_OWNER_ID>

The package is published to PyPI and can be executed directly using uvx. Use the aci-mcp command with the appropriate subcommand to start the desired server.

Commands

• apps-server: Starts the apps-specific MCP server.
• unified-server: Starts the unified MCP server with unlimited tool access.

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

# Run help to see available commands
uvx aci-mcp --help

The aci-mcp-apps server uses a default linked_account_owner_id (set via the server's startup flags). However, to support multi-user use cases within the limitations of the MCP protocol, you can override this default for a specific tool call.

When calling a tool, include the aci_override_linked_account_owner_id parameter in your arguments object. The server will use this value for the execution and then strip it from the arguments before passing them to the underlying ACI function.

{
  "name": "name_of_the_tool",
  "arguments": {
    "aci_override_linked_account_owner_id": "user_specific_id",
    "actual_tool_arg": "value"
  }
}

The VibeOps MCP server dynamically loads and exposes functions from the VibeOps controller as MCP tools.

When a tool name matches a function available on the VibeOps backend, the server executes that function by sending a POST request to /v1/functions/{name}/execute.

Note on Search Parameters: Due to compatibility issues with certain MCP clients (like Cursor's auto mode), the limit and offset parameters have been removed from the search function's input schema.

To run the VibeOps MCP server, you must provide the following environment variables:

• VIBEOPS_API_KEY: Your API key for the VibeOps controller. This is required and must be set.
• VIBEOPS_BASE_URL: The base URL for the VibeOps controller. Defaults to https://controller.aci.dev.

If VIBEOPS_API_KEY is not provided, the server will raise a ValueError and fail to start.

export VIBEOPS_API_KEY="your_api_key_here"
export VIBEOPS_BASE_URL="https://controller.aci.dev"

The aci-mcp-unified server requires specific environment variables to connect to the ACI backend and perform documentation searches.

• ACI_API_KEY: Required. Your ACI API key. The server will fail to start if this is not set.
• ACI_SERVER_URL: The base URL for the ACI API. Defaults to https://api.aci.dev/v1.

export ACI_API_KEY="your_api_key_here"
export ACI_SERVER_URL="https://api.aci.dev/v1"

When executing an ACI function, the server uses a default linked_account_owner_id (provided at server startup). However, you can pass aci_override_linked_account_owner_id in the tool arguments to execute the function on behalf of a different user.

{
  "name": "[ACI_EXECUTE_FUNCTION_NAME]",
  "arguments": {
    "function_name": "my_function",
    "function_arguments": { ... },
    "aci_override_linked_account_owner_id": "user_123"
  }
}

The ACI_SEARCH_DOCS tool allows you to perform vector searches against ACI documentation. It requires a single string parameter q representing your search query.

{
  "name": "ACI_SEARCH_DOCS",
  "arguments": {
    "q": "how to use the python sdk"
  }
}

The Unified MCP Server exposes three primary tools to MCP clients (like Claude Desktop or Cursor):

1. ACI Search Functions: Used to discover available ACI functions. Note that limit and offset parameters are handled internally (defaulting to limit: 15 and offset: 0) to improve compatibility with certain AI agents.
2. ACI Execute Function: Used to execute a specific ACI function.
3. ACI_SEARCH_DOCS: A specialized tool for searching ACI.dev documentation, SDKs (Python & TypeScript), and usage examples.

Multi-user Account Overrides

To support multi-user scenarios via the MCP protocol, you can override the default linked_account_owner_id when calling the ACI Execute Function tool by providing the aci_override_linked_account_owner_id argument.