singularity-forge/gitbook/configuration/mcp-servers.md
ace-pm b29c12d5e5 refactor(native): rename gsd_parser.rs to forge_parser.rs
Final rebrand: rename remaining Rust source file to complete the gsd → forge
transition. All parser references already use forge_parser after earlier commits.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 14:58:21 +02:00

1.7 KiB

MCP Servers

SF can connect to external MCP (Model Context Protocol) servers for local tools, internal APIs, self-hosted services, or integrations not built in as native extensions.

Configuration Files

SF reads MCP config from these project-local paths:

  • .mcp.json — repo-shared config (safe to commit)
  • .sf/mcp.json — local-only config (not shared)

If both exist, server names are merged and the first definition found wins.

Supported Transports

Transport Config Shape Use When
stdio command + optional args, env, cwd Launching a local MCP server
http url Connecting to an already-running server

Examples

stdio Server

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "/absolute/path/to/python3",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "API_URL": "http://localhost:8000"
      }
    }
  }
}

HTTP Server

{
  "mcpServers": {
    "my-http-server": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Verifying a Server

After adding config, verify from a SF session:

  1. mcp_servers — confirms SF sees the config
  2. mcp_discover(server="my-server") — confirms the server starts and responds
  3. mcp_call(server="my-server", tool="<tool>", args={...}) — confirms a real tool call works

Tips

  • Use absolute paths for executables and scripts
  • Set required environment variables directly in the MCP config's env block
  • Use .mcp.json for team-shared servers; .sf/mcp.json for machine-local ones
  • If a server depends on local paths or personal secrets, keep it in .sf/mcp.json