# Connect your agent

> Switch on Folio's MCP server, then connect any agent that speaks MCP over HTTP to your workspace, from Folio's own terminal or from outside Folio.

Source: https://semvia.io/docs/quickstart/connect-your-agent

Folio serves your workspace over [MCP](https://modelcontextprotocol.io/specification), 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](https://www.anthropic.com/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.

Figure: The Integrations section of Folio's settings. Enable MCP server is checked. MCP / local server port reads 30037. MCP endpoint holds the server address in a read-only field.

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:

  ```
  {
    "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](https://semvia.io/docs/quickstart/connect-your-agent#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.

Figure: An example with Claude Code: its /mcp panel in Folio's terminal, listing the folio project server as connected with 49 tools.

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](https://www.w3.org/TR/skos-reference/) (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.

[Next: Model your first class](https://semvia.io/docs/quickstart/model-your-first-class): Define a class with a required name, and watch Folio flag an installation that has none.
