Platform MCP server

The FYAI platform MCP server lets an AI assistant work with your FYAI project through the Model Context Protocol. Connect it to Claude Code, Claude Desktop, VS Code (GitHub Copilot) or any other MCP client, and the assistant can create and update agents, run them, build and execute workflows, load knowledge bases, read usage and observability data, and hand tasks to FYAI agents — all with your credential and inside your project.

It's a thin layer over the Platform API: each tool makes one or a few authenticated REST calls to the agent, catalog and integration services.

This is the other direction from the MCP Gateway

The platform MCP server lets an outside assistant use FYAI. The MCP Gateway does the reverse: it lets your FYAI agents use tools from other MCP servers.

What it gives your assistant

The server has 306 tools in 23 categories:

Category	Tools	What the assistant can do
Agents	23	Create, search, update and delete agents; run an agent synchronously or asynchronously; manage its identity, context prompts and request contexts
Teams	10	Build multi-agent teams and manage membership and ordering
LLM configs	8	Create and manage model connections; see a config's resolved settings; attach functions
Functions	7	Create and manage the tools agents call
Chat	13	Start chat sessions, read and search transcripts, hand off, justify, end and delete sessions
Missions	22	Create and manage missions and their steps, presets and node approvals
Workflows	34	Create, validate, instantiate and execute workflows; schedules, metrics, single-node runs, approvals, test scenarios, eval results and run-state
Integrations	21	Create integrations, manage their secrets, grant and revoke access, see shared integrations
Webhooks	7	Create webhooks, rotate their secrets and read delivery logs
Event sources	5	Manage inbound event channels
Catalog	15	Manage manifests and elements
Data sources	12	Create, test, refresh and read data sources; push data; use data source templates
Knowledge	16	Create knowledge bases, ingest text, URLs, git repositories, Confluence and manifests, check readiness and search
Memories	8	Observe, search, edit, consolidate and clear agent memory
Dashboards	9	Build dashboards, add elements and set layouts
Programs	31	Build programs, phases and activities; run them; resolve checkpoints; manage documents and knowledge
Delegation	7	Hand a task or workflow run to the platform and follow it to completion
Execution environments	9	Manage environments, check status, list and invoke tools, generate runner tokens
Promotions	7	Analyse, execute and roll back promotions between projects; deploy environments
Testing	11	Create and run agent and team test cases; see metrics and coverage
Observability	13	Agent and team summaries, errors and audit logs; usage; risk registry; platform models
Templates	17	Browse and instantiate templates for agents, teams, functions, models, workflows, manifests and integrations
Analytics	1	Send activity events

Every tool is listed in the MCP tool reference.

These operations are deliberately not available through the server:

• creating, changing or deleting templates (browsing and instantiating them is available)
• platform-wide administration, analytics and model seeding
• exporting, deleting or purging tenant and user data
• runner registration and lifecycle calls
• file-upload endpoints (icons, profile pictures, document and skill file uploads)

Requirements

• An FYAI API key. Create one under Settings → API Keys — see Authentication. Its Access level limits what the assistant can do: Read for an assistant that only looks, Write for one that builds and runs things.
• Python 3.11 or later.
• Node.js 18 or later, if you install with npm.
• Access to the @fyainz/platform-mcp package. It's published to GitHub Packages under the fyainz organisation, so you need a GitHub account with read access to it. Ask FYAI if you don't have access.

Install

With npm

Point the @fyainz scope at GitHub Packages and sign in with a GitHub personal access token that has the read:packages scope:

npm login --registry=https://npm.pkg.github.com --scope=@fyainz

Then install:

npm install @fyainz/platform-mcp --registry=https://npm.pkg.github.com

Installing creates a Python virtual environment inside the package and installs the server into it. Run it with:

npx @fyainz/platform-mcp

With Python

From a copy of the package source:

pip install .
fyai-platform-mcp

python -m fyai_platform_mcp.server also starts it.

Configure

The server reads its settings from environment variables:

Variable	Required	Purpose
FYAI_API_KEY	Yes (or FYAI_API_TOKEN)	Your API key. Sent as X-API-Key.
FYAI_API_TOKEN	Alternative	A bearer access token. A value starting fyai_ is treated as an API key. Access tokens expire within minutes, so prefer FYAI_API_KEY.
FYAI_AGENT_URL	No	Override the agent API URL. Defaults to https://agent.fyai.co.nz.
FYAI_CATALOG_URL	No	Override the catalog API URL. Defaults to https://catalog.fyai.co.nz.
FYAI_INTEGRATION_URL	No	Override the integration API URL. Defaults to https://integration.fyai.co.nz.
FYAI_FUI_URL	No	Override the web app URL used in links the delegation tools return. Defaults to https://fyai.co.nz.

The server reads the credential on every request, so you can rotate a key without restarting your MCP client.

warning

Don't paste your key into a configuration file that's committed to source control. Set FYAI_API_KEY in the environment your MCP client starts from, or use your client's secret handling.

Connect your MCP client

The server uses the stdio transport: your MCP client starts it as a local process and talks to it over standard input and output. There's no hosted HTTP endpoint for it.

Claude Code

Add it to your project's .mcp.json (or your user configuration):

{
  "mcpServers": {
    "fyai-platform": {
      "command": "npx",
      "args": ["@fyainz/platform-mcp"]
    }
  }
}

Export FYAI_API_KEY in the shell you start Claude Code from; the server inherits it. Then run /mcp in Claude Code to check the server is connected.

To hand whole tasks to FYAI agents from Claude Code, see Delegating from Claude Code.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "fyai-platform": {
      "command": "npx",
      "args": ["@fyainz/platform-mcp"],
      "env": {
        "FYAI_API_KEY": "fyai_..."
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "fyai-platform": {
      "command": "npx",
      "args": ["@fyainz/platform-mcp"],
      "env": {
        "FYAI_API_KEY": "fyai_..."
      }
    }
  }
}

Using it well

• Everything happens in the key's project. The assistant sees and changes only the project the API key belongs to. Use a separate key per project.
• Prefer asynchronous runs. Each tool call times out after 60 seconds. run_agent waits for the agent to finish, so use run_agent_async and get_agent_run_status for anything that might take longer.
• Chat sessions run in the background. start_chat_session returns as soon as the session exists. Poll get_chat_session_state or get_chat_conversations for progress. Pass chat_type as group (with team_configuration_id) or agent (with target_agent_id) — other values are rejected.
• Running a workflow takes a mission. Either call instantiate_workflow and then execute_workflow with the returned mission ID, or use run_workflow from the delegation tools, which does both and tracks the run.
• Updates are partial. update_* tools change only the fields you pass.
• Errors come straight from the API. A failed tool call reports the HTTP status and the API's detail. See the error table in Platform API.

Troubleshooting

Symptom	Cause and fix
The client shows the server as failed or "Connection closed"	The server process couldn't start. Run npx @fyainz/platform-mcp (or fyai-platform-mcp) in a terminal to see the error. A common cause is a Python older than 3.11.
Every tool returns 401	FYAI_API_KEY isn't set in the environment the client started the server from, or the key has been revoked or has expired.
Tools return 403	The key's Access level is too low for that operation. Create a key with more access.
A tool can't find an agent or workflow you can see in the web app	The key belongs to a different project from the one you're looking at.
run_agent times out	The run took longer than 60 seconds. Use run_agent_async.