Skip to content
Get packs

Guide · Agent skill

How to use the Managing MCP Servers agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The managing-mcp-servers skill teaches an AI agent how to set up and manage MCP servers, the add-ons that give an assistant extra tools such as documentation lookups, browser control or GitHub access. It is written for ThinkRail, a desktop application with built-in pi MCP support. After reading this guide you will know how to install the skill, ask for changes in plain language, and understand what the agent will and will not do on your machine.

Managing MCP ServersJetBrains/thinkrail · Apache-2.0

Quick start

  1. 1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/, or into .claude/skills/ in a project, or upload it under Settings → Capabilities → Skills in the Claude apps.
  2. 2Make your request. Describe the server or tool and the result you want in plain language, for example adding a documentation server or diagnosing a failing tool.
  3. 3Review the config change. Check which file the agent edits: the user-level mcp.json for personal servers or .pi/mcp.json for a shared repository server.
  4. 4Replace secrets with references. Make sure tokens are referenced as ${ENV_VAR}, command output, or handled by sign-in rather than written into the file.
  5. 5Approve or sign in. If the server needs it, approve a repository server or click Sign in for an OAuth server in Settings › MCP servers.
  6. 6Test the tool. Ask the agent to use the new tool. If it is still missing or failing, ask it to diagnose the problem using the skill's checks.

What does the skill make the agent do?

Without this skill, an agent has no reliable procedure for connecting MCP servers. With it, the agent knows where server configuration lives, how to write entries in the correct JSON format, and how to explain the approval and sign-in steps that only you can complete in the app.

The agent edits JSON configuration files rather than running commands. It uses a user-level file for personal servers and a repository-level .pi/mcp.json for servers you want to share with a project. For anything that needs approval or sign-in, it points you to Settings › MCP servers.

  • Adds, changes, removes, enables or disables MCP servers.
  • Diagnoses an MCP tool that is missing, needs sign-in, fails or was blocked.
  • Keeps secrets out of configuration files by referencing environment variables or command output.
  • Explains how MCP tools are named and called.

How do you install the managing-mcp-servers skill?

Download the ZIP from this page and unzip it. The skill is a folder containing SKILL.md. Place that folder in one of two locations: ~/.claude/skills/ to make it available to you everywhere, or .claude/skills/ inside a specific project to make it available only there.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

  • Personal install: unzip into ~/.claude/skills/.
  • Project install: unzip into .claude/skills/ in the project folder.
  • Claude apps: upload under Settings → Capabilities → Skills.

How do you trigger the skill with a request?

You do not need a special command. The skill's description tells the agent when to use it, so ask in ordinary language. Requests about adding, changing, removing, enabling or disabling an MCP server, or about a tool that is missing, needs sign-in, fails or was blocked, are the right kind of request.

Be specific about the server or tool and the outcome you want. The agent will say when a step belongs to you, such as approving a repository server or signing in.

  • "Add the documentation MCP server at https://example.com/mcp to my user config."
  • "My GitHub MCP tool says it needs sign-in. Diagnose it."
  • "Disable the browser server for this project."
  • "Put the shared docs server in this repository so the team gets it."

How are MCP servers configured?

Both configuration files use the same format: a top-level mcpServers object, where each key is a server name. A server can be a remote URL or a local command with arguments. Pin package versions in args rather than using @latest.

Never paste a real token into a file or into chat. The skill tells the agent to reference an environment variable as ${ENV_VAR}, use command output as !command, or let you sign in.

  • User level: usually ~/.pi/agent/mcp.json, available in every project.
  • Repository: .pi/mcp.json in the project, tracked in git. It runs only after you approve it in Settings.
  • Exposure options: deferred (the default for repositories, loaded with tool_search), direct (a few always-useful tools), or hidden.
  • Repository servers only load when you trust the project.
{ "mcpServers": { "docs": { "url": "https://example.com/mcp" }, "browser": { "command": "npx", "args": ["-y", "@playwright/mcp@0.0.83"] } } }

How do you set up the GitHub server?

GitHub is a recipe rather than a preset. It uses GitHub's hosted MCP server and authenticates with your GitHub CLI sign-in, so you need the GitHub CLI (gh) installed and signed in. The skill adds the entry to your user-level file, and Settings › MCP servers offers the same entry under Paste JSON.

The URL ending in /readonly is GitHub's documented read-only mode. Use the non-readonly URL only when you ask for tools that change data. If gh is logged out, the header command fails rather than sending an empty token; run gh auth login in a terminal to fix it.

  • Read-only is the default choice for this recipe.
  • If the server rejects the CLI token, the skill suggests a token in an environment variable instead, referenced as ${GITHUB_TOKEN}.
  • Whether GitHub accepts the CLI token's scopes for every toolset is not verified by the skill.
{ "mcpServers": { "github": { "url": "https://api.githubcopilot.com/mcp/readonly", "headers": { "Authorization": "!t=$(gh auth token) && echo \"Bearer $t\"" } } } }

What safety rules does the skill follow?

Repository servers are a security boundary. A server defined in .pi/mcp.json does not run until you approve it, and any later change to its entry needs approval again. Approve only servers you have reviewed, especially from projects you did not write.

ThinkRail asks you before a tool call that may change data. If you deny or cancel a call, the agent should not retry it without asking you first. The skill also says subagents cannot call MCP tools, so the main agent makes those calls and passes results along.

  • Do not paste API tokens into the chat; the agent should not be trusted with raw secrets.
  • Review a repository server before approving it.
  • Expect to approve or sign in yourself in Settings › MCP servers; the agent does not restart ThinkRail.

What people use it for

  • Connecting a documentation source so the assistant can look up current reference material.
  • Adding GitHub access in read-only mode for reviewing issues and pull requests.
  • Sharing a team browser-automation server through a committed .pi/mcp.json file.
  • Diagnosing a missing MCP tool after a server was blocked or needs sign-in.
  • Disabling a server for one project without removing it from your user-level file.

Frequently asked questions

Is the managing-mcp-servers skill free?

The source material lists its licence as Apache-2.0. It does not state prices, so check the listing on this page for any other terms. The skill itself is a SKILL.md file you download and install.

What do I need to use this skill?

You need the ThinkRail desktop application with its built-in pi MCP support. Stdio-based servers such as @playwright/mcp need Node.js and npx, and the GitHub recipe needs the GitHub CLI (gh) installed and signed in, plus a GitHub account.

Where do I install the skill?

Unzip the downloaded ZIP into ~/.claude/skills/ for all projects or into .claude/skills/ in one project. In the Claude apps you can upload it under Settings → Capabilities → Skills.

Does the skill run commands like pi mcp add?

No. The skill tells the agent never to run pi commands, because ThinkRail has no pi executable. The agent edits JSON configuration files and sends you to Settings › MCP servers for approvals and sign-ins.

Can I put my API key in the config file?

No. The skill says never to write a secret into either configuration file. Reference an environment variable as ${ENV_VAR}, use command output, or sign in instead.

Why is my MCP tool missing or needs sign-in?

Ask the agent to diagnose it. Common causes covered by the skill include a repository server that is not yet approved, an OAuth server that needs Sign in, a gh session that is logged out, or a tool that was blocked. Repository servers only load when you trust the project.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits ThinkRail users who want to add, share or troubleshoot MCP servers without editing files by hand. It is not useful for other AI tools or for anyone who expects to paste raw API tokens into chat, since the skill is designed to avoid that.

Download the skill