MCP Protocol

Lighthouse MCP Server

Use Case: The Lighthouse MCP Server is a Model Context Protocol (MCP)-compliant backend that allows AI agents to interact with decentralized storage through the Lighthouse network. It exposes a standardized set of tools for file management, dataset handling, and IPFS integration — enabling trusted, encrypted data workflows for AI systems.

Step 0: Clone & Set Up the MCP Agent Tool

First, clone the Lighthouse MCP Agent

# Clone the repository
git clone https://github.com/lighthouse-web3/lighthouse-agent-tooling.git
cd lighthouse-agent-tooling


# Install dependencies
pnpm install

# Build the MCP server 
pnpm run build --filter @lighthouse-tooling/mcp-server

🔐 Step 1: Setup Environment & Authentication

1.1 Get Credentials

• Lighthouse API Key: files.lighthouse.storage

1.2 Set Environment Variables

export LIGHTHOUSE_API_KEY="your-lighthouse-api-key"
export LOG_LEVEL="info"

1.3 Start The Server

pnpm run dev --filter @lighthouse-tooling/mcp-server

By default, the server starts locally and listens for incoming MCP client connections.

Available MCP Tools

1. lighthouse_upload_file

Uploads a file to Lighthouse’s decentralized network, with optional encryption.

Parameters

• filePath (string, required) – Path to file on local disk.

• encrypt (boolean, optional) – Whether to encrypt before upload.

• accessConditions (object, optional) – Define file access rules.

Example :

{
  "filePath": "./data/model.bin",
  "encrypt": true
}

2. lighthouse_create_dataset

Creates a structured dataset with metadata and grouped files.

Parameters

• name (string, required) – Dataset name.

• description (string, optional) – Description for reference.

• files (array, required) – Array of file paths.

• metadata (object, optional) – Additional metadata (version, tags).

Example :

{
  "name": "training-v1",
  "description": "Image training dataset",
  "files": ["./images/train.zip", "./labels.csv"]
}

3. lighthouse_fetch_file

Retrieves a file by its CID and optionally decrypts it locally.

Parameters

• cid (string, required) – IPFS CID.

• outputPath (string, optional) – Destination path.

• decrypt (boolean, optional) – Whether to decrypt.

Example:

{
  "cid": "QmYwAPJzv5CZsnA...",
  "decrypt": true
}

Programmatic Usage

You can embed the MCP server into a custom Node.js environment.

Example:

import { LighthouseMCPServer } from "@lighthouse-tooling/mcp-server";

const server = new LighthouseMCPServer({
  lighthouseApiKey: process.env.LIGHTHOUSE_API_KEY,
  logLevel: "info",
  enableMetrics: true,
});

await server.start();
console.log("Server running...");

Testing

Tests include:

• Unit tests for each service

• Integration tests for tool calls

• Performance validation

# Run all tests
pnpm test --filter @lighthouse-tooling/mcp-server

# With coverage
pnpm run test:coverage --filter @lighthouse-tooling/mcp-server