MCP configuration reference

This page documents how MCP servers are configured in Syntic Code and the three transports Amara can use to reach them. Servers are defined in JSON under an mcpServers object, which can live in your project’s .syntic/ directory or in your user-level configuration. Project entries are shared with anyone who clones the repository; user entries stay private to you.

Configuration schema

Each key under mcpServers is the server’s name, and its value describes how to connect. The available fields depend on the transport.

{
  "mcpServers": {
    "local-fs": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "env": { "LOG_LEVEL": "info" }
    },
    "internal-api": {
      "transport": "http",
      "url": "https://mcp.example.com",
      "headers": { "Authorization": "Bearer ${API_TOKEN}" }
    }
  }
}

Common fields are transport (one of stdio, sse, or http) and an optional enabled flag. Values wrapped in ${...} are read from environment variables at startup, so you can keep secrets out of committed files.

Transports

stdio launches the server as a local child process and communicates over standard input and output. It takes command, an optional args array, and an optional env map. Use it for servers you run locally, such as tools distributed as npm or Python packages.

SSE connects to a remote server using Server-Sent Events for streaming responses. It takes a url and an optional headers map for authentication. Choose SSE for hosted servers that stream results as they are produced.

HTTP connects to a remote server over standard request-response HTTP. Like SSE it takes a url and optional headers. Use it for stateless remote services and internal APIs behind a gateway.

Scopes and management

Servers resolve with project configuration taking precedence over user configuration, letting a repository override a personal default of the same name. Manage entries with syntic mcp add, syntic mcp list, syntic mcp get, and syntic mcp remove, all of which accept --scope project or --scope user. Disable a server without deleting it by setting "enabled": false, and rotate credentials by updating the referenced environment variables rather than the config file itself.