DocumentationMCP integration

MCP integration

Set up MCP so Codex, Claude Desktop, Cursor, and other clients can access your projects.

Before connecting

Prepare an HTTPS-accessible Feronavi instance and an API token issued by that instance. Create a token on the product’s API tokens page. Start with read-only access, then enable writes only when your tasks require them.

Account permissions, project scope, IP restrictions, expiration, and revocation determine available capabilities. Replace both https://feronavi.example.com and fero_xxx in the examples.

Choose a transport

The MCP endpoint is /api/v1/mcp, using Streamable HTTP. Clients that support remote MCP can use this URL with Bearer authentication.

For clients that require local stdio, use the feronavi-mcp bridge. Install Node.js 20 or later and npm on the machine running the bridge; the Feronavi source code is not required. The bridge forwards protocol requests, obtains tool descriptions from the server, and does not cache business data.

npx -y feronavi-mcp@0.1.0 --url https://feronavi.example.com --token fero_xxx

feronavi-mcp is published on npm. The current version is 0.1.0. You can also verify the command from a terminal:

npx -y feronavi-mcp@0.1.0 --help

Pin the tested version in client configuration to control when you upgrade.

Claude Desktop and Cursor

Use this mcpServers structure in the Claude Desktop configuration or Cursor’s .cursor/mcp.json. Keep tokens in protected local configuration or environment variables.

{
  "mcpServers": {
    "feronavi": {
      "command": "npx",
      "args": ["-y", "feronavi-mcp@0.1.0"],
      "env": {
        "FERONAVI_URL": "https://feronavi.example.com",
        "FERONAVI_TOKEN": "fero_xxx"
      }
    }
  }
}

VS Code

Use the servers structure in .vscode/mcp.json:

{
  "servers": {
    "feronavi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "feronavi-mcp@0.1.0"],
      "env": {
        "FERONAVI_URL": "https://feronavi.example.com",
        "FERONAVI_TOKEN": "fero_xxx"
      }
    }
  }
}

Codex and other clients

Add this configuration to ~/.codex/config.toml, then reconnect to MCP in Codex:

[mcp_servers.feronavi]
command = "npx"
args = ["-y", "feronavi-mcp@0.1.0"]

[mcp_servers.feronavi.env]
FERONAVI_URL = "https://feronavi.example.com"
FERONAVI_TOKEN = "fero_xxx"

Replace the sample URL and token with your instance details. For other clients, add a remote server through the MCP configuration supported by your current version, or register the bridge as a stdio command. Client configuration fields differ; do not copy another client’s outer structure unchanged.

After connecting, ask the agent to discover tools, list accessible projects, and read work items from a specific project. Confirm the instance, account, and scope before proceeding.

Query and update projects

Start with a request like:

Review unfinished work in this iteration and group risks by owner. Propose changes first. After my confirmation, update statuses and assignments, then read back and verify the results.

Agents use the same business services and permission rules as the product interface. External clients manage their own planning and confirmation experience; explicitly require confirmation before changes. The built-in assistant provides a confirmation flow inside the product.

Troubleshoot connections

  • Check that the client machine can reach the HTTPS endpoint.
  • Check token validity, expiration, revocation, and IP restrictions.
  • Check the token’s access level and project allowlist.
  • If a write result is unclear, query the current data before retrying.

Type a keyword to search all documentation.