Skip to content

Quickstart Connect your agent

New to Folio? Start here

Connect your agent

Folio serves your workspace over MCP, the protocol AI agents use to call tools. Once your agent is connected, it can read, write and validate your workspace, and query the graph it represents.

Any agent that can connect to an MCP server over HTTP works. The examples use Claude Code, from Anthropic.

Before you start

Have an agent ready that can connect to an MCP server over HTTP.

Turn on the MCP server

The server is off until you switch it on.

  1. Open Settings and go to Integrations.
  2. Switch on Enable MCP server.
  3. Leave MCP / local server port at its default, 30037.
Settings → Integrations with the MCP server on.

Run your agent from Folio's terminal

This is the shortest path. Folio's terminal already knows where the server is.

  1. Click Terminal in the activity bar, press Ctrl+` (on every platform), or run Open Terminal from the command palette. The terminal opens in the workspace folder.

  2. Opening a workspace in Folio adds a folio entry to the .mcp.json file in the workspace folder. Folio creates the file if it is missing and keeps any servers already listed there:

    .mcp.json
    {
      "mcpServers": {
        "folio": {
          "type": "http",
          "url": "http://127.0.0.1:${FOLIO_MCP_PORT:-30037}/api/v1/mcp"
        }
      }
    }

    The terminal sets FOLIO_MCP_PORT to the port Folio is running on, so the address is right even after you change the port.

  3. Start your agent in that terminal. An agent that reads .mcp.json when it starts finds the folio server there. If yours doesn't, give it the address from MCP endpoint, as in Connect from outside Folio.

  4. Check that your agent lists folio as a connected MCP server.

For example, with Claude Code: run claude, which reads .mcp.json when it starts. Answer yes when it asks whether you trust the folder, and approve the folio server if it asks about that too. Then type /mcp. The folio server is listed under the project's servers as connected, with its tool count.

Example: Claude Code's /mcp in Folio's terminal lists folio as connected.

Connect from outside Folio

For an agent running outside Folio, register the server with your agent once, by its address.

  1. In Settings → Integrations, copy the address in MCP endpoint. On a default install it is http://127.0.0.1:30037/api/v1/mcp.
  2. Add that address to your agent as an MCP server of type HTTP (sometimes called Streamable HTTP), named folio.
  3. Check that your agent lists folio as a connected MCP server.

For example, with Claude Code:

claude mcp add --transport http folio http://127.0.0.1:30037/api/v1/mcp

Then run claude mcp list and check that folio is connected.

Your first prompt

Check the connection by asking your agent what's in your workspace. Paste this into your agent:

Use the folio MCP server. List my workspaces and select the one I have open in Folio. If more than one is open, ask me which. Then tell me what each file in it adds to the graph.

The agent lists your open workspaces and asks which one to use if more than one is open. Then it reads each file.

Ask your agent to…

Run these in a new, empty workspace. Each builds something from nothing, then has Folio check or answer it. The second uses the Simple Knowledge Organization System (SKOS), a standard vocabulary for taxonomies.

  • Build a film domain model with titles, release dates, box-office revenue and streaming licenses, add a few sample films, then validate them against it and fix what Problems reports.
  • Create a taxonomy of power plant asset classes in SKOS, from thermal and renewable down to nuclear, gas turbine, solar and wind, and check it with the SKOS Taxonomy profile.
  • Model our legal entities and who owns whom, with ownership percentages, add a parent with a few layers of subsidiaries, then query for every subsidiary of the parent, however far down.
  • Build a product catalog taxonomy with English, French and German labels, then query for every category that is missing a German label.