Connecting MCP servers

Add an MCP server to Fabric Agents — config schemas for HTTP, SSE, and stdio transports, with worked examples.

The fastest way to connect an MCP server is to tell the agent:

"Add Linear as a source."

It finds the server URL, picks the right transport, sets up OAuth, writes the guide.md, and validates the connection. You don't have to touch a config file.

This page covers the manual path — useful when you're writing your own MCP server, connecting to something niche, or debugging what the agent set up.

Where the config lives

Every MCP source is a folder:

~/.fabric-agent/workspaces/{workspace-id}/sources/{source-slug}/
├── config.json
├── guide.md          # agent-facing usage guide
├── permissions.json  # Explore-mode allowlist
└── icon.svg          # optional

config.json holds the transport and auth details. Everything below is the schema for that file.

HTTP (streamable) — the default

The most common MCP setup. Point it at a URL and you're done.

{
  "id": "linear_a1b2c3d4",
  "name": "Linear",
  "slug": "linear",
  "provider": "linear",
  "type": "mcp",
  "icon": "https://linear.app/favicon.ico",
  "tagline": "Issue tracking and sprint planning",
  "enabled": true,
  "mcp": {
    "url": "https://mcp.linear.app/mcp",
    "authType": "oauth"
  }
}

Fields inside mcp:

Field	Type	Description
`url`	string, required	MCP endpoint.
`transport`	`"http"` \| `"sse"` \| `"stdio"`	Optional. Defaults to `"http"` when `url` is present.
`authType`	`"none"` \| `"bearer"` \| `"oauth"`	See Authentication.
`headers`	`Record<string, string>`	Static headers on every request — for example, a tenant ID or a routing hint.
`headerNames`	`string[]`	For credential-backed multi-header auth.
`clientId`	string	OAuth client ID. Stored in config (not a secret) for token refresh.

SSE (legacy remote)

If the server only speaks Server-Sent Events rather than streamable HTTP, set transport explicitly:

{
  "mcp": {
    "url": "https://example.com/mcp",
    "transport": "sse",
    "authType": "bearer"
  }
}

Streamable HTTP is preferred for new servers; SSE remains supported for compatibility.

stdio (local subprocess)

Point Fabric Agents at a command and it'll speak MCP over the subprocess's stdin/stdout. Popular for community-built connectors that run locally rather than as a web service.

{
  "id": "filesystem_b5c6d7",
  "name": "Filesystem",
  "slug": "filesystem",
  "provider": "filesystem",
  "type": "mcp",
  "icon": "📁",
  "tagline": "Read and write files in a specific folder",
  "enabled": true,
  "mcp": {
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"],
    "env": {
      "FS_MAX_FILE_SIZE": "10485760"
    }
  }
}

Fields specific to stdio:

Field	Type	Description
`command`	string, required	Executable to spawn. Typically `npx`, `uvx`, `bun`, or an absolute binary path.
`args`	`string[]`	Command arguments.
`env`	`Record<string, string>`	Extra environment variables. Merged on top of the inherited parent env (minus sensitive vars — see below).

Environment isolation

When Fabric Agents spawns a stdio MCP server, it forwards process.env but strips known-sensitive variables so they can't leak to third-party code:

ANTHROPIC_API_KEY
AWS_* (all AWS vars)
GITHUB_TOKEN, GH_TOKEN
and other provider secrets

If an MCP server genuinely needs one of these (say, a GitHub MCP needs GITHUB_TOKEN), pass it through the env block in config.json — that's an explicit opt-in per source.

Windows notes

npx and uvx work but use backslash path separators. Fabric Agents doesn't mangle them, but double-check quoting in your args array.
Subprocess termination uses the Windows kill API instead of POSIX signals; you shouldn't notice the difference unless you're debugging a server that traps SIGTERM.

Validating the connection

Once you save config.json, the app reconnects and calls listTools() immediately as a health check. Outcomes:

Green source icon in the sidebar — healthy, tools available.
Yellow "Needs auth" — transport is fine, credentials are missing or expired. See Authentication.
Red "Unreachable" — transport itself failed. Check the URL, firewall, or subprocess command.

You can also run fabric-cli sources to list all sources and their status from the command line — handy when debugging on a headless server.

URL normalisation

URLs you paste are lightly normalised: a trailing slash is stripped. Everything else is used verbatim — no rewriting of scheme, path, or query.

Authentication — auth types and OAuth flow.
Sources overview — how sources are enabled, per-workspace scope, credential storage.
Permissions — scope MCP tools in Explore mode.

On this page