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

# MCP Server Installation & Setup

> Connect the IFÁ Labs MCP Server to Claude Desktop, Cursor, Windsurf, TRAE, and other MCP-compatible AI clients with step-by-step configuration.

This page walks through installing the IFÁ Labs MCP Server and connecting it to every major MCP-compatible client. The server runs locally on your machine and communicates with IFÁ Labs' deployed oracle contracts on your behalf.

***

## Prerequisites

Before installing, confirm you have the following:

* **Node.js v18 or higher** — the MCP server is a Node.js process. Check your version with `node --version`.
* **npm or yarn** — for installation.
* An MCP-compatible client — Claude Desktop, Cursor, Windsurf, TRAE, or any other listed in [Supported MCP Clients](/what-is-the-ifa-labs-mcp-server).

<Note>
  No wallet, private key, or gas is required to run the IFÁ Labs MCP Server. All oracle reads are view calls — free, read-only, and require no on-chain signing.
</Note>

***

## Step 1: Install the MCP Server

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
        npm install -g @ifalabs/mcp-server
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
        yarn global add @ifalabs/mcp-server
    ```
  </Tab>

  <Tab title="Run without installing">
    ```bash theme={null}
        npx @ifalabs/mcp-server
    ```

    Use this to try the server without a global install. For persistent client integrations, a global install is recommended.
  </Tab>
</Tabs>

Verify the installation:

```bash theme={null}
ifa-mcp --version
```

***

## Step 2: Configure Your Client

Select your MCP client below and follow the configuration steps.

<Tabs>
  <Tab title="Claude Desktop">
    Claude Desktop supports MCP servers via a JSON configuration file.

    <Steps>
      <Step title="Locate the config file">
        Open or create the Claude Desktop MCP configuration file:

        * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
        * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
        * **Linux:** `~/.config/Claude/claude_desktop_config.json`
      </Step>

      <Step title="Add the IFÁ Labs server">
        Add the following to your `mcpServers` block:

        ```json theme={null}
                {
                  "mcpServers": {
                    "ifalabs": {
                      "command": "ifa-mcp",
                      "args": ["--network", "base-mainnet"]
                    }
                  }
                }
        ```
      </Step>

      <Step title="Restart Claude Desktop">
        Fully quit and relaunch Claude Desktop. The IFÁ Labs tools will appear in the tools panel on the next launch.
      </Step>

      <Step title="Verify the connection">
        In a new Claude conversation, ask:

        > "What is the current USDT/USD price from IFÁ Labs?"

        Claude should call the `get_asset_price` tool and return a live on-chain value.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor">
    Cursor supports MCP servers via its settings panel or a project-level config file.

    <Steps>
      <Step title="Open MCP settings">
        Go to **Cursor Settings** → **Features** → **MCP Servers** → **Add New MCP Server**.
      </Step>

      <Step title="Configure the server">
        Choose the format that matches your operating system:

        **macOS / Linux:**

        ```json theme={null}
                {
                  "mcpServers": {
                    "ifalabs": {
                      "command": "ifa-mcp",
                      "args": ["--network", "base-mainnet"]
                    }
                  }
                }
        ```

        **Windows — Option A (recommended): use `node` with the local dist path**

        ```json theme={null}
                {
                  "mcpServers": {
                    "ifalabs": {
                      "command": "node",
                      "args": ["C:/Users/YOUR_USERNAME/OneDrive/Desktop/ifamcpserver/dist/index.js", "--network", "base-mainnet"]
                    }
                  }
                }
        ```

        Replace `YOUR_USERNAME` with your Windows username and adjust the path to match wherever you cloned or built the project.

        **Windows — Option B: use `npx` (no local path required)**

        ```json theme={null}
                {
                  "mcpServers": {
                    "ifalabs": {
                      "command": "npx",
                      "args": ["-y", "@ifalabs/mcp-server", "--network", "base-mainnet"]
                    }
                  }
                }
        ```

        <Note>
          On Windows, Cursor cannot resolve the `ifa-mcp` binary directly because npm wraps global binaries in a `.cmd` file that Cursor does not execute. Use the `node` or `npx` format instead. macOS and Linux users can use `ifa-mcp` directly.
        </Note>
      </Step>

      <Step title="Save and verify">
        Save the settings. Open a new Cursor chat and ask:

        > "Use IFÁ Labs to get the current CNGN/USD price."

        Cursor should call the MCP tool and return a live price.
      </Step>
    </Steps>

    **Alternatively**, add a `.cursor/mcp.json` file to your project root for project-scoped configuration using the same OS-appropriate format above:

    ```json theme={null}
        {
          "mcpServers": {
            "ifalabs": {
              "command": "ifa-mcp",
              "args": ["--network", "base-mainnet"]
            }
          }
        }
    ```
  </Tab>

  <Tab title="Windsurf">
    <Steps>
      <Step title="Open MCP configuration">
        Go to **Windsurf Settings** → **MCP** → **Add Server**.
      </Step>

      <Step title="Add the server config">
        ```json theme={null}
                {
                  "mcpServers": {
                    "ifalabs": {
                      "command": "ifa-mcp",
                      "args": ["--network", "base-mainnet"]
                    }
                  }
                }
        ```
      </Step>

      <Step title="Restart and verify">
        Restart Windsurf and confirm the IFÁ Labs server appears in the active MCP servers list.
      </Step>
    </Steps>
  </Tab>

  <Tab title="TRAE">
    <Steps>
      <Step title="Open MCP settings">
        Go to **TRAE Settings** → **MCP Servers** → **Add Server**.
      </Step>

      <Step title="Add the server config">
        ```json theme={null}
                {
                  "mcpServers": {
                    "ifalabs": {
                      "command": "ifa-mcp",
                      "args": ["--network", "base-mainnet"]
                    }
                  }
                }
        ```
      </Step>

      <Step title="Restart and verify">
        Restart TRAE and verify the server is active before starting a new session.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Other MCP Clients">
    Any MCP-compatible client that supports stdio-based servers can connect to the IFÁ Labs MCP Server using the following configuration:

    ```json theme={null}
        {
          "mcpServers": {
            "ifalabs": {
              "command": "ifa-mcp",
              "args": ["--network", "base-mainnet"]
            }
          }
        }
    ```

    **Windows users:** replace `ifa-mcp` with `node` and provide the full path to `dist/index.js`, or use `npx -y @ifalabs/mcp-server` instead.

    Refer to your client's documentation for where to place this configuration.
  </Tab>
</Tabs>

***

## Configuration Options

The IFÁ Labs MCP Server accepts the following arguments:

| Argument          | Values                                               | Default         | Description                                      |
| ----------------- | ---------------------------------------------------- | --------------- | ------------------------------------------------ |
| `--network`       | `base-mainnet`, `base-sepolia`, `assetchain-testnet` | `base-mainnet`  | The network to read oracle data from             |
| `--rpc-url`       | Any valid RPC URL                                    | Network default | Override the default RPC endpoint                |
| `--max-price-age` | Integer (seconds)                                    | `3600`          | Default staleness threshold for freshness checks |
| `--port`          | Integer                                              | `3000`          | Port for SSE transport mode (if applicable)      |
| `--log-level`     | `silent`, `error`, `info`, `debug`                   | `error`         | Logging verbosity                                |

**Example — connect to Base Sepolia for development:**

```bash theme={null}
ifa-mcp --network base-sepolia --log-level info
```

**Example — use a custom RPC provider:**

```bash theme={null}
ifa-mcp --network base-mainnet --rpc-url https://base-mainnet.g.alchemy.com/v2/YOUR_API_KEY
```

<Tip>
  For production workflows, use a dedicated RPC provider — Alchemy, QuickNode, or Infura — rather than the public Base RPC endpoint. Public endpoints are rate-limited and not suitable for high-frequency tool calls.
</Tip>

***

## Connecting to Testnet

For development and testing against live testnet oracle data, point the server at Base Sepolia:

```json theme={null}
{
  "mcpServers": {
    "ifalabs": {
      "command": "ifa-mcp",
      "args": ["--network", "base-sepolia"]
    }
  }
}
```

All supported assets are available on Base Sepolia with the same asset IDs as mainnet. Prices reflect testnet oracle state and may differ from mainnet values.

***

## Using with Custom Agents and Frameworks

For LangChain, CrewAI, AutoGen, or any custom MCP-compatible agent framework, the server can be connected programmatically:

```javascript theme={null}
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "ifa-mcp",
  args: ["--network", "base-mainnet"],
});

const client = new Client(
  { name: "my-agent", version: "1.0.0" },
  { capabilities: {} }
);

await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log(tools);

// Call a tool
const result = await client.callTool({
  name: "get_asset_price",
  arguments: { asset: "USDT/USD", network: "base-mainnet" },
});

console.log(result);
```

<Note>
  Windows users running programmatic integrations should use the `node` command with the full path to `dist/index.js` in the `StdioClientTransport` config, or use `npx` with `-y @ifalabs/mcp-server`.
</Note>

***

## Verifying the Connection

Once configured, verify the server is connected and returning live data with these test prompts in your client:

| Test Prompt                                         | Expected Behaviour                                                                              |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| "List all supported IFÁ Labs assets"                | Returns all asset symbols and IDs via `get_supported_assets`                                    |
| "What is the current USDT/USD price from IFÁ Labs?" | Returns live price via `get_asset_price`                                                        |
| "Is the CNGN/USD feed fresh?"                       | Returns age and freshness status via `check_price_freshness`                                    |
| "Get the ZARP/USD asset ID"                         | Returns `0x12373a3b1c4827c84bf6d7b11df100442695d0abfdb7a20d30a41d67d58e75a8` via `get_asset_id` |

If any of these fail, work through the [troubleshooting steps](#troubleshooting) below.

***

## Troubleshooting

**`ifa-mcp: command not found`** The global install did not complete successfully or the npm global bin directory is not in your `PATH`. Run `npm list -g @ifalabs/mcp-server` to confirm installation, then check your `PATH` configuration. On Windows, use the `node` or `npx` format instead.

**Connection closed immediately on Windows** Cursor and some other clients on Windows cannot resolve the `ifa-mcp` binary. Switch to the `node` format with the full path to `dist/index.js`, or use `npx -y @ifalabs/mcp-server`. See the Cursor tab above for exact config blocks.

**Server appears in client but tools return errors** Confirm the `--network` argument matches a supported network. Check `--log-level info` output for RPC connection errors.

**Prices return stale or unexpected values on testnet** Testnet oracle state is independent of mainnet. Prices on Base Sepolia reflect testnet relayer activity and may be less fresh than mainnet feeds during low-activity periods.

**Client doesn't recognise the server after config change** Most MCP clients require a full restart — not just a settings save — to pick up configuration changes. Fully quit and relaunch your client.

**Rate limit errors on the default RPC** Switch to a dedicated RPC provider using `--rpc-url`. See the [Configuration Options](#configuration-options) table above.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Available Tools" icon="wrench" href="/available-tools">
    Full reference for every tool the IFÁ Labs MCP Server exposes.
  </Card>

  <Card title="Example Queries" icon="message" href="/example-queries">
    Practical prompts and workflows for using IFÁ Labs via MCP clients.
  </Card>
</CardGroup>