MCP quickstart

MCP servers give Syntic Code tools it does not have out of the box: your issue tracker, a database, internal docs, a design tool. This page gets one server connected and working in a few minutes. The full details are on MCP servers.

Before you begin

Syntic Code is installed and you are signed in (syntic auth status).
You know how to reach the server. Server authors usually give one of two things:
- a command that starts the server on your machine (often npx …, uvx … or a binary), or
- a URL for a server that runs somewhere else.
For a command, the program it calls (Node, Python and so on) is installed.

Add a server and check it

Add the server

From your shell, in the project folder. For a server that runs as a local program:

syntic mcp add notes -- npx -y @example/notes-mcp ~/notes

For a remote server:

syntic mcp add tracker https://mcp.tracker.example/mcp

The first word after add is the name you give the server. Everything after the command (or --) is passed to the program unchanged, flags included.

Check it answers

syntic mcp list --check

--check starts each local server once and reports whether it answered and how many tools it offers. Remote servers are listed with their address.

Use it

Start a session and ask for something the server can do:

Search my notes for anything about the Q3 migration and summarize it.

The first time the agent calls one of the server’s tools, you are asked to allow it, as with any other tool. Run /mcp to see the server’s state and tool count.

Where the server was saved

syntic mcp add saves to the local scope by default: only you, only in this project. Pick another scope with --scope:

Scope	File	Who gets the server
`local` (default)	`.syntic/settings.local.json`	You, in this project. The file stays out of git.
`project`	`.mcp.json` at the project root	Everyone who clones the repository.
`user`	`~/.syntic/.mcp.json`	You, in every project.

syntic mcp get notes          # shows the server, its scope and settings

Use a server everywhere

syntic mcp add notes --scope user -- npx -y @example/notes-mcp ~/notes

syntic mcp add tracker --scope project https://mcp.tracker.example/mcp
git add .mcp.json && git commit -m "Add tracker MCP server"

Teammates are asked to approve the server the first time they start Syntic Code in the project. Keep tokens out of the shared file by referring to environment variables (below).

Two more examples

A local server that needs a secret

syntic mcp add db -e DATABASE_URL=postgres://localhost/dev -- npx -y @example/postgres-mcp

-e KEY=VALUE sets an environment variable for the server program. Repeat it for more.

A remote server that signs in

Many hosted servers use OAuth. Add the server, then sign in once:

syntic mcp add tracker https://mcp.tracker.example/mcp
syntic mcp login tracker

Your browser opens on the service’s sign-in page. When it finishes, the token is stored securely and refreshed for you. You can also sign in from /mcp: select the server and press Enter.

If the service gave you a token instead, send it as a header:

syntic mcp add tracker https://mcp.tracker.example/mcp --header "Authorization: Bearer $TRACKER_TOKEN"

Edit the file directly

All scopes use the same format, so you can also write the file by hand. A project .mcp.json:

{
  "mcpServers": {
    "notes": {
      "command": "npx",
      "args": ["-y", "@example/notes-mcp", "${HOME}/notes"]
    },
    "tracker": {
      "type": "http",
      "url": "https://mcp.tracker.example/mcp",
      "headers": { "Authorization": "Bearer ${TRACKER_TOKEN}" }
    }
  }
}

${VAR} is replaced with the environment variable when the server starts, and ${VAR:-fallback} gives a default. Changes take effect in the next session.

A server’s setup notes written as a JSON object can be added in one line with syntic mcp add-json <name> '<json>'.

Troubleshooting

Problem	What to do
`syntic mcp list --check` says the server did not answer	Run the server’s command yourself in a terminal to see its error. Missing runtimes (Node, Python) are the usual cause.
The server shows as “needs sign-in”	`syntic mcp login <name>`, or `Enter` on it in `/mcp`.
A project server never starts	Trust the folder first, then approve the server when asked. `syntic mcp reset-project-choices` asks again if you declined.
The server is slow to start	Sessions do not wait for it; its tools appear when it is ready. In `-p` runs, raise the wait with `SYNTIC_MCP_TIMEOUT` (milliseconds).
The same name exists in two scopes	`syntic mcp remove <name> --scope <scope>` removes one of them.

Next steps

MCP servers: every option, transports, sign-in, limits and policy.
Permission rules: allow a whole server with mcp__<server>__*.

Parallel work with worktrees MCP servers