Connecting an MCP Server

A Model Context Protocol server exposes a set of tools. In FYAI, one MCP function represents one server, and every tool the server advertises becomes available to the agents the function is assigned to, unless you hide it.

There are two kinds:

• MCP server (stored as MCP Stdio (Subprocess)): FYAI starts the server as a subprocess, for example with npx or uvx.
• MCP over HTTP (stored as MCP HTTP (SSE)): FYAI connects to a server someone else runs.

tip

If a provider's MCP server uses OAuth sign-in, look for an OAuth-brokered integration for it in the Marketplace instead. Each person then connects their own account under Connected Accounts rather than sharing one key.

1. Store the credentials in an integration

If the server needs a token, create an integration for it first and add the token as a secret. See Managing Integrations. Don't paste credentials into the function itself: environment values and headers on the function are visible to anyone who can open it.

2. Create the function

1. Go to Resources → Functions and click +.

2. Choose MCP server or MCP over HTTP.

3. Fill in Function Name and Description. The description is shown alongside the server's own tool descriptions.

4. Fill in the connection:

   MCP server (stdio)

   Field	Example
   Command (e.g. npx)	npx
   Arguments (JSON array e.g. ["-y", "pkg"])	["-y", "@modelcontextprotocol/server-github"]
   Server Placement	Workspace — needs the session filesystem (default) or Stateless — wraps a remote API
   .npmrc Content	Only for packages from a private npm registry

   MCP over HTTP

   Field	Example
   URL	https://mcp.example.com/mcp
   Headers (JSON object)	{"Authorization": "Bearer {{API_TOKEN}}"}

5. Click Link Integration and attach the integration that holds the credentials.

6. Click Create.

Choosing a placement

Placement	Use when
Workspace	The server reads or writes files the agent also uses. It runs beside the chat session's filesystem. This is the safe default.
Stateless	The server only wraps a remote API. It can be pooled and shared, which is cheaper, but it gets no session directory. A file-based server placed here sees an empty directory.

3. How credentials reach the server

When the server starts, the platform resolves every secret and environment variable on the linked integrations:

• Stdio servers receive each one as an environment variable with the same name. To expose a secret under a different variable name, add an Environment entry on the Definition tab whose value is integration:<integration id>:<secret name>, for example SONAR_TOKEN = integration:38:SONARQUBE_TOKEN.
• HTTP servers: {{NAME}} placeholders in header values are replaced with the matching secret. Any linked secret that is not already a header name is also sent as a header with that name.
• For a private npm package, put the registry settings in .npmrc Content. It supports ${ENV_VAR} substitution, for example //npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}, with the token held as a secret on a linked integration.

Secret values are resolved at start-up and are never stored on the function.

4. Check it starts, then choose its tools

Open the function's Definition tab. For MCP functions it shows these cards:

Card	What it tells you
Server	Command, arguments (one per line), Placement, Environment or Headers as key/value rows, Registry auth and .npmrc.
Health	healthy, failing or never started here, with Last start, Last good (time and tool count) and Package (version if pinned; an npx spec without a version shows as unpinned). Retry start and Show full log help diagnose a failure.
Discovered tools	Every tool the server advertised at the last successful discovery.
Egress	The hosts the server talks to, or opaque when they can't be determined. A subprocess or remote server controls its own network access.
Approval	The server default plus counts of per-tool pins and hidden tools. See it per consumer opens the Consumers tab.
Secrets	The secret names resolved for this server.

Starting a server requires credentials, so discovery runs as one of your agents. Click Rediscover on Discovered tools to start the server and refresh the list.

warning

If a server fails to start, agents that use it silently lose its tools. The chat does not fail. Check the Health card after any change.

In the Discovered tools table:

• On: switch a tool off to hide it. Hidden tools are removed from the model's tool list, not just left unapproved.
• Kind: read or write, guessed from the tool's name.
• Approval: inherit, never require or always require for that one tool.
• Hide write tools switches off every tool whose name reads as a write in one click.

Click Update to save tool choices.

5. Test and assign

• Use the Test tab to run a tool directly or let an agent decide. See Testing Functions.
• Assign the function to agents. See Adding Tools to Agents.

Troubleshooting

Symptom	Likely cause
This function produced no callable tools in the console	The MCP handshake failed. Open the log: common causes are a wrong package name, missing environment variables, or npx-only flags such as -y passed to uvx.
Health shows failing after it used to work	An unpinned npx package changed, or a credential expired. Pin the version in Arguments (for example [email protected]) and check the integration's secrets.
"could not start right now — the sandbox pool is full" in chat	A temporary capacity issue, not a configuration problem. Send another message to retry.
A file-based server sees no files	Placement is Stateless. Change it to Workspace.

Related

• Functions
• Function Settings
• MCP Gateway: exposing FYAI tools to external MCP clients (the reverse direction)