Getting Started

A Step-by-step guide to set up Polytope with Bluetext, run the MCP server, and connect coding agents like Claude Code, Roo and Cline.

Make sure to have Polytope installed and set up on your computer. You can find instructions on how to do so here:

• For macOS users

• For Windows users

• For Linux users

1. Setup

First, create a new directory for your project.

We recommend you initialise the git repository in the project directory. To do so, run the following command in your new directory.

git init

Then, make a polytope.yml file inside it that contains the following:

include:
  - repo: gh:bluetext-io/bluetext

Bluetext is a repository of predefined MCP tools, and these tools are made available to Polytope through the inclusion of the Bluetext repository in this file. We can now run the MCP server to use Bluetext with your preferred coding agent. The agent will use these tools to perform development tasks or generate application components.

2. Running the MCP

To start the server, run the following command in your terminal:

pt run --mcp

This command locates the highest-level polytope.yml file in your filesystem or git repository. This file becomes the main Polytope configuration that defines which tools are available.

3. Connecting the MCP to an Agent

Connecting your coding agent to the MCP server allows the agent to access Polytope’s tools directly during development. You can connect the MCP server to any coding agent that supports custom MCP server configuration. Based on our testing, Claude Code, Cline and Roo work particularly well. This section outlines the setup process for all three, allowing you to use your preferred agent.

Setup for Roo

To connect Claude Code to your MCP, configure your mcp_settings.json file to look like this:

{
  "mcpServers": {
    "polytope": {
      "type": "streamable-http",
      "url": "http://localhost:31338/mcp",
      "disabled": false
    }
  }
}

To navigate to this file, from the Roo UI, "Views and More Actions" then "MCP Servers" then "Edit Global MCP".

NOTE: To ask questions switch to ask mode, and to generate code you should be in code mode. By default it is set to architect more, which will not help when generating code with Bluetext.

Setup for Claude Code

To connect Claude Code to your MCP, run the following command:

claude mcp add polytope-mcp http://localhost:31338/mcp

Setup for Cline

To connect Cline to the MCP server, configure your cline_mcp_settings as follows:

{
  "mcpServers": {
    "polytope": {
      "type": "streamableHttp",
      "url": "http://localhost:31338/mcp",
      "disabled": false
    }
  }
}

To navigate to this file from the Cline chat interface, select "MCP Servers" from the top, then navigate to the "Configure" tab, and from the bottom select "Configure MCP Servers".

When

4. Starting to Prompt

Before continuing, you can consult the flight check document to test if Bluetext, Polytope, and the agent are configured to work. Once you have your Polytope MCP running, and you have ensured your agent is connected to the MCP server, you can start to tell your agent what to create! Once you have prompted your agent, it will ask you to approve tool calls that look similar to the following:

Once you start approving these tool calls, you will see that the Polytope UI gets populated with containers, services, volumes, and more. While previously empty, the Polytope interface should now look something like this:

If you have started creating a project and close the Polytope MCP server (ctrl + C), or if your IDE crashes, you can re-open your project with the following command:

pt run default --mcp

If you suspect Bluetext or Polytope are not configured correctly, you can consult the troubleshooting documentation.