How to Configure MCP Servers in MCPlato

Answer first: add a .mcp.json file to the root of an MCPlato workspace, define one or more servers under mcpServers, then review and enable them in AI Partner MCP Settings. The enabled server set belongs to the workspace, so its sessions use the same tool boundary.

This guide covers MCPlato as an MCP client: connecting a workspace to local or remote MCP servers. It includes configuration examples, the discovery order implemented by MCPlato, a security checklist, and failure modes worth testing before a server touches important files or accounts.

Scope and review date: This is first-party MCPlato documentation, reviewed on July 13, 2026 against the desktop configuration service. MCP servers are third-party software unless explicitly bundled by MCPlato. Their behavior, permissions, data handling, and availability must be evaluated separately.

What MCP changes inside a workspace

The Model Context Protocol standardizes how an AI application can discover and call external tools, resources, and prompts. An MCP server can expose capabilities such as database queries, project search, issue tracking, browser automation, or access to a deliberately limited directory.

In MCPlato, the useful boundary is the workspace:

• a project can declare the servers it needs in .mcp.json;
• the AI Partner MCP settings show discovered servers and their source;
• servers can be enabled or disabled for that workspace;
• sessions in the workspace inherit the same enabled configuration;
• unrelated workspaces do not need to share the same project-specific tool set.

That model matches the broader directory-as-conversation approach: context and tools remain attached to the project where the work lives.

Quick setup: a local filesystem server

Use a disposable test directory first. Replace the example path with an absolute path that contains only files you are comfortable exposing to the server.

1. Confirm the runtime is available

The example server is distributed through npm, so the machine needs a working Node.js and npx installation. You can verify both from a terminal:

node --version
npx --version

2. Create .mcp.json in the workspace root

{
  "mcpServers": {
    "project-files": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/absolute/path/to/a/test-folder"
      ]
    }
  }
}

This configuration starts a local MCP server as a child process and communicates with it over standard input and output. The final argument is the server's allowed directory, not a decorative label. Keep that root as narrow as the task permits.

The filesystem server and its current arguments are maintained in the official Model Context Protocol servers repository. Check its README before copying a production configuration because package names and flags can change.

3. Review the server in MCPlato

Open the workspace's AI Partner MCP Settings. MCPlato scans the project configuration and shows the server name, source, transport type, command, and arguments. Enable the server only after those details match what you intended to run.

4. Test a bounded tool call

Start with a prompt that is easy to verify and does not write anything:

List the filenames in the MCP test folder. Do not open, edit, rename, or delete files.

Confirm that the returned files come only from the allowed root. Then test a harmless read before considering writes or external actions.

How MCPlato discovers MCP servers

MCPlato aggregates multiple configuration sources. For plugin, system, and workspace definitions, a same-name entry from the higher-priority source is used. Custom workspace entries should use a unique server name.

The workspace-level enabled state is stored separately from the discovered definition. This allows a server to exist in a plugin, system file, or .mcp.json while remaining disabled for a particular workspace.

Supported configuration shapes

MCPlato supports three MCP transport types in its server configuration.

Local stdio example

{
  "mcpServers": {
    "example-local-server": {
      "type": "stdio",
      "command": "/absolute/path/to/server-binary",
      "args": ["--read-only"]
    }
  }
}

Use an absolute executable path when shell PATH behavior may differ between a terminal and a desktop application. Pin a package or binary version when reproducibility matters.

Remote HTTP example

{
  "mcpServers": {
    "example-remote-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

This only demonstrates the configuration shape. Do not send project data to an example endpoint. Follow the server vendor's authentication instructions and confirm its retention, authorization, and logging behavior before using real material.

Workspace-scoped MCP versus a global configuration

Use a workspace .mcp.json when the server exists for one project's workflow, such as a project repository, a research corpus, or a specific internal API. Use a system-level definition only when the server is intentionally available across projects.

Workspace scoping reduces accidental tool sprawl, but it is not a sandbox by itself. A broadly configured server can still access more than the visible project directory. Effective control depends on all of the following:

1. the roots, endpoints, credentials, and flags passed to the server;
2. the operating-system permissions of the server process;
3. the MCPlato permission mode and approval decisions;
4. the server implementation's own authorization and validation;
5. the user's review of tool calls and resulting changes.

For a wider evaluation framework, use the downloadable AI agent harness pilot scorecard and the accompanying agent harness comparison.

Security checklist before enabling a server

Download the reusable MCP client setup and security checklist or apply these checks directly:

• Limit file roots. Give a filesystem server one test or project directory, not a home directory or entire disk.
• Keep secrets out of Git. Do not commit reusable API keys, tokens, cookies, or private headers to .mcp.json.
• Inspect what runs. Verify the package owner, source repository, release history, command, arguments, and install scripts.
• Prefer least privilege. Start read-only and add write or network capabilities only when the workflow proves it needs them.
• Keep approval boundaries. Require review for writes, commands, messages, purchases, publishing, and other external side effects.
• Use disposable test data. Validate discovery, errors, and recovery before connecting customer, financial, legal, or production data.
• Pin and record versions. A moving package tag can change behavior without changing .mcp.json.
• Disable unused servers. Reducing the active tool set makes prompts, approvals, and incident investigation easier to reason about.

Troubleshooting

A repeatable validation sequence

For every new MCP server, run the same small acceptance test:

1. Record the server name, source URL, package or release version, transport, and configuration owner.
2. Start it with disposable credentials and data.
3. Confirm capability discovery matches the server's documentation.
4. Run one read-only tool call and verify the exact data boundary.
5. Trigger one expected error and confirm it fails clearly without corrupting state.
6. Test whether sensitive actions require the intended approval.
7. Restart MCPlato and confirm the configuration is reproducible.
8. Disable the server and verify that its tools disappear from the workspace.

This sequence produces evidence that can be reviewed later. A successful demo call is not enough to prove that authentication, recovery, permissions, and upgrades are safe.

Next steps

• Download MCPlato for macOS or Windows.
• Try the coding agent workspace with a deliberately limited project directory.
• Read why MCPlato treats the directory as the conversation boundary.
• Use the MCP client checklist when reviewing additional servers.

MCP makes tools portable. The important engineering decision is still the boundary around those tools: which workspace can see them, what they can access, what requires approval, and how failures are reviewed.