ai

The Ampersand MCP server exposes the tools from the Ampersand AI SDK as native capabilities that you can connect to your agents. It supports both SSE (server-sent events) and stdio communication modes, enabling integration with a wide range of agent frameworks. When run in stdio mode, you configure the server via mcp.json to point to the latest MCP server package and provide your project, integration name, and group reference, along with your API key. The server then presents hundreds of connectors (tools) that agents can invoke to interact with customer SaaS tools through Ampersand.

To use the server, connect your agent workflow to the configured MCP server (either via SSE or stdio). In SSE mode, specify the proper URL and, if needed, headers with your API key. In stdio mode, the server runs locally and the agent communicates over a standard input/output channel. You’ll typically pass a project id, integration name, and group reference to align with your Ampersand workspace, and the server will expose a suite of tools corresponding to the connectors and capabilities available in Ampersand.

Prerequisites:

• Node.js and npm installed on your system (Node.js 14+ recommended).
• Access to the internet to fetch packages from npm.
• An Ampersand project with API key and appropriate project/integration/group references.

Install the MCP server (Node/npm-based) using npx as shown in the example below, or adapt to your preferred package manager by pre-installing the package if desired.

1. Ensure prerequisites are installed (example for Debian/Ubuntu):

curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
sudo apt-get install -y nodejs
node -v
npm -v

2. Initialize and run the MCP server via npx (stdio mode):

# This uses the mcp-server package from npm registry
npx -y @amp-labs/mcp-server@latest --transport stdio \
  --project <AMPERSAND_PROJECT_ID> \
  --integrationName <AMPERSAND_INTEGRATION_NAME> \
  --groupRef <AMPERSAND_GROUP_REF>

3. If you prefer SSE mode, configure the mcp.json with the SSE URL and optional headers as described in the README:

{
  "mcpServers": {
    "@amp-labs/mcp-server": {
      "url": "https://mcp.withampersand.com/v1/sse?project=<AMPERSAND_PROJECT_ID>&integrationName=<AMPERSAND_INTEGRATION_NAME>&groupRef=<AMPERSAND_GROUP_REF>",
      "headers": {
        "x-api-key": "<AMPERSAND_API_KEY>"
      }
    }
  }
}

Environment and configuration tips:

• Always keep AMPERSAND_API_KEY, AMPERSAND_PROJECT_ID, AMPERSAND_INTEGRATION_NAME, and AMPERSAND_GROUP_REF securely managed. Do not commit them to version control.
• When using stdio mode, ensure the host process has permissions to read/write to the console or pipes used by the agent.
• If you encounter network or authentication issues, verify that the API key is correct and that the project/integration/groupRef values match your Ampersand workspace.
• The MCP server exposes 150+ connectors/tools; consult the official documentation to discover available tools and how to call them from your agent framework.
• For local development, consider linking your local SDK changes into the MCP workflow to test new tool behavior quickly.