MCP Servers

This guide explains how to configure MCP Servers for agents in Sink, enabling them to access external tools and data sources.

What is an MCP Server?

An MCP (Model Context Protocol) Server is a standard way for agents to access external tools and data sources. For example, an MCP Server can provide:

• File system access
• Database queries
• Web API calls
• Code analysis tools
• And more

Sink supports two types of MCP Servers:

• stdio: Executable programs running locally
• http: Remote HTTP services

MCP configuration file

MCP Servers are defined through the mcp.json configuration file, which should be located at one of:

• Workspace level: <workspace>/.sink/mcp.json
• User level: ~/.sink/mcp.json
• Builtin level (pre-configured in the distribution)

Workspace-level configuration overrides user-level, and user-level overrides builtin-level.

Basic format

The basic structure of mcp.json:

{
  "mcpServers": {
    "server-id": {
      "type": "stdio",
      "command": "executable-path",
      "args": ["--arg1", "--arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

Configure stdio-type servers

Stdio-type servers are executable programs running locally. Agents communicate with them via standard input/output.

Basic example

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "mcp-server-filesystem",
      "args": ["--root", "/home/user"],
      "env": {
        "DEBUG": "false"
      }
    }
  }
}

Field descriptions

Run via npx

You can run npm packages directly through npx:

{
  "mcpServers": {
    "web-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-server-web-search"]
    }
  }
}

Environment variables

If an MCP Server requires special environment variables (such as API keys), specify them in env:

{
  "mcpServers": {
    "openai": {
      "type": "stdio",
      "command": "mcp-server-openai",
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Note: Do not store sensitive API keys directly in mcp.json. Instead, set environment variables in settings.json and reference them in mcp.json. For example:

settings.json:

{
  "env": {
    "OPENAI_API_KEY": "sk-..."
  }
}

mcp.json:

{
  "mcpServers": {
    "openai": {
      "type": "stdio",
      "command": "mcp-server-openai",
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
      }
    }
  }
}

Configure HTTP-type servers

HTTP-type servers are remote services accessed over the network.

Basic example

{
  "mcpServers": {
    "api-service": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer token-here"
      }
    }
  }
}

Field descriptions

Disable a server

You can temporarily disable an MCP Server without deleting its configuration, using the metadata.disabled field:

{
  "mcpServers": {
    "disabled-server": {
      "type": "stdio",
      "command": "some-command",
      "metadata": {
        "disabled": true
      }
    }
  }
}

You can also use environment variables for dynamic control:

{
  "mcpServers": {
    "optional-server": {
      "type": "stdio",
      "command": "some-command",
      "metadata": {
        "disabled": "${DISABLE_SERVER}"
      }
    }
  }
}

Then set in settings.json:

{
  "env": {
    "DISABLE_SERVER": "false"
  }
}

Built-in MCP Server

Sink automatically registers a built-in sink MCP Server for each task, providing the following tools:

Task management tools

• task_complete — Mark task as complete
• task_spawn — Create a subtask. Parameters: prompt (description), profileId (profile selection), executionMode (individual or team), awaitCompletion (wait for subtask to finish before returning), managed (managed flag), configOverrides (override config defaults), questionnaireAnswers (answer profile questionnaire questions)
• task_info — Query task information
• task_send_message — Send message to another task. Supports two types: task_message (plain message) and task_reopen_request (ask the target task to reopen itself after completion). Use task_info with taskId: "parent" to discover your parent task’s ID
• task_reopen — Reopen a completed task

Configuration query tools

• profile_list — List all Profiles
• profile_get — Get specific Profile details
• runtime_list — List all Runtimes
• runtime_get — Get specific Runtime details
• skill_list — List all Skills
• skill_get — Get specific Skill details
• mcp_list — List all MCP Servers
• mcp_get — Get specific MCP Server details

Cron scheduling tools

Agents can manage scheduled tasks through the following tools:

• cron_set — Set a timed notification for the current task (sends a message when triggered)
• cron_spawn — Set up automatic subtask creation on a schedule (creates a new task with a specified Profile when triggered). Note: requires task_spawn to be enabled; if task_spawn is disabled, cron_spawn is automatically unavailable.
• cron_remove — Remove a scheduled task
• cron_list — List all scheduled tasks for the current task

The built-in sink MCP Server does not need to be configured in mcp.json; all tasks automatically have access to it.

Common MCP Servers

The following are some commonly used open-source MCP Servers:

File system access

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    }
  }
}

Web browsing

{
  "mcpServers": {
    "puppeteer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

Git repositories

{
  "mcpServers": {
    "git": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git"]
    }
  }
}

Troubleshooting

MCP Server fails to start

Symptom: MCP Server connection fails when task starts

Checklist:

1. Confirm the executable exists and is executable:

   which command-name
   ls -l /path/to/command
   

2. Try running the server manually to check for errors:

   /path/to/mcp-server
   

3. Check logs for more information (if debug mode is configured)

Environment variables not working

Symptom: ${VAR} is not replaced in mcp.json

Reason: Variable not defined in settings.json or doesn’t exist in shell environment

Solution:

1. Confirm the variable is defined in settings.json:

   {
     "env": {
       "VAR": "value"
     }
   }
   

2. Or confirm the environment variable is set in your shell:

   export VAR="value"
   sink gateway
   

HTTP server connection fails

Symptom: HTTP-type server connection times out or is rejected

Checklist:

1. Confirm URL is correct and service is online:

   curl -H "Authorization: Bearer token" https://api.example.com/mcp
   

2. Check if firewall is blocking the connection
3. Verify the authentication token is valid

Next steps

1. Manage Profiles — Assign different MCP Servers to different agents
2. Configure Runtimes — Learn how to configure agent runtimes
3. Quick Start Tutorial — Create and run your first task