Connect Claude Code to MCP servers through Toolstile

On this page

To add Toolstile to Claude Code, run claude mcp add --transport http toolstile 'https://toolstile.com/mcp', then type /mcp inside Claude Code and sign in through your browser. You pick a Toolstile workspace during that sign-in. Claude Code gets no tools until a workspace admin grants the new agent access to specific MCP connections, so the last step happens in the Toolstile dashboard.

One entry in Claude Code then reaches every MCP connection you allow in that workspace. You do not add each provider's server to Claude Code separately.

What you need

Claude Code installed and signed in.
A Toolstile account with at least one MCP connection in the workspace you want Claude Code to use. If you have none yet, follow getting started or browse integrations for provider-specific setup.
A browser on the same machine, or the remote sign-in steps described below.

Connected servers must be public HTTPS endpoints. A server that Claude Code would normally launch as a local stdio process cannot be added to Toolstile's managed service.

Add Toolstile to Claude Code

From the project directory where you want to use it:

Shell

claude mcp add --transport http toolstile 'https://toolstile.com/mcp'

toolstile is only a local label; any name made of letters, numbers, hyphens and underscores works. The URL is Toolstile's gateway. Do not paste a provider's MCP URL or an /app/… dashboard address here.

Claude Code stores the entry at one of three scopes:

Scope	Flag	Where it lives	Use it when
Local (default)	`--scope local`	`~/.claude.json`, under this project's path	You want Toolstile in this project only, privately
User	`--scope user`	`~/.claude.json`	You want Toolstile in every project on this machine
Project	`--scope project`	`.mcp.json` in the repository root	You want to commit the entry so teammates get it

For most people, user scope is the practical choice because one Toolstile workspace covers all your projects:

Shell

claude mcp add --transport http --scope user toolstile 'https://toolstile.com/mcp'

A project-scoped entry shares only the configuration. Each person who opens the repository still signs in to Toolstile with their own account, and Claude Code asks them to approve project servers from .mcp.json before using them. If the same name exists in several scopes, the local entry wins over project, and project wins over user.

If you also added Toolstile as a custom connector on claude.ai, Claude Code can list that connector as well. A server added in Claude Code takes precedence over a claude.ai connector with the same URL, and /mcp shows the connector as hidden.

Start Claude Code, type /mcp and press Enter. Select toolstile; its status shows that it needs authentication. Choose to authenticate and Claude Code opens your browser. You can also start sign-in from the shell with claude mcp login toolstile.

In the browser:

Sign in to Toolstile if prompted.
Choose the Workspace this Claude Code entry should use. Personal and team workspaces have separate catalogs and allowances.
Review the suggested agent and device names. Edit names lets you pick something recognizable, such as Claude Code (work laptop).
Choose Approve and complete any Allow connection screen.

Claude Code stores and refreshes the resulting token itself. If the browser does not open, copy the URL Claude Code prints. If the redirect back fails after you approve, paste the full callback URL from the browser's address bar into Claude Code's prompt.

Working over SSH. Claude Code waits for sign-in on the remote machine's loopback address. Add &device_name= and that machine's name (for example from hostname -s) to the end of the sign-in link it prints, then open the link in your local browser. After approving, Toolstile shows a command to run on the remote machine to complete the sign-in. Alternatively, run npx toolstile auth login and npx toolstile mcp setup on that machine: sign-in uses a code you approve in any browser, with nothing to run afterwards. See set up a whole machine from the terminal.

Grant Claude Code access in Toolstile

New agents start with no MCP access. Open the Toolstile workspace you chose, find the agent under Devices & agents, then go to Access and pick the MCP connection. In the agent's column, set each tool to Allow, Require approval or Block, then choose Save changes. Require approval means a person approves each individual call before it runs.

A reasonable starting point for a coding agent is to allow read tools (search issues, read files, fetch logs), require approval for anything that writes to shared state, and block destructive tools. Everything, including ones added later gives full access, including future tools; explicit blocks still win. In a team workspace, an admin grants each agent individually. See permissions for how grants, policies and blocks combine.

When Claude Code calls a tool marked Require approval, it receives a result explaining that approval is needed, with a link to Toolstile's Approvals page. Approving does not run the call. Ask Claude Code to retry the same call afterwards.

Check that it works

claude mcp list in a terminal shows each server's status, such as ✔ Connected or ! Needs authentication.
/mcp inside Claude Code shows the server, its status and the tools it currently exposes.
In Toolstile, the connection's Test tool action can load the agent's permitted tool list without running anything.

Then ask Claude Code for one read-only lookup with harmless input, for example "list my open issues using Toolstile". Check Activity in the same Toolstile workspace for a matching entry. Tool names seen through the gateway can differ from the upstream server's names.

How Claude Code permissions and Toolstile access fit together

Both layers apply, and each can stop a call independently.

Toolstile decides which tools exist for this agent. A blocked or ungranted tool is not in the list Claude Code receives, and a call to it is refused even if Claude Code remembers the name. Toolstile's rules apply wherever the agent connects from and cannot be edited from the developer's machine.

Claude Code decides whether to ask you before calling a tool it can see. Its permission rules refer to MCP tools as mcp__<server>__<tool>, using the label you chose:

JSON

{
  "permissions": {
    "allow": ["mcp__toolstile__search_issues"],
    "deny": ["mcp__toolstile__delete_issue"]
  }
}

mcp__toolstile__* matches every tool from the entry. Claude Code evaluates deny, then ask, then allow. Check exact tool names in /mcp before writing rules. The Claude Code permissions guide covers how to combine these with Toolstile grants. If you run Claude Code with --dangerously-skip-permissions, read what that flag skips first.

In short: use Toolstile to decide what an agent can reach at all, and Claude Code rules to decide what runs without prompting in your session.

Direct servers or Toolstile

You can keep adding servers to Claude Code directly with claude mcp add. That works well for one or two personal servers, local stdio tools, or anything on a private network, which Toolstile cannot reach.

Toolstile fits better when the same connections serve several agents or several people: provider sign-in happens once in Toolstile, each agent gets its own grant, and access can be revoked from the dashboard. Both can be used at the same time in Claude Code. If you are choosing servers, see the best MCP servers for Claude Code.

Troubleshooting

/mcp shows "Needs authentication" but no browser opens. Select the server and authenticate again, or run claude mcp login toolstile. Copy the printed URL manually if needed. If you set an Authorization header on this entry earlier, Claude Code reports a failed connection instead of falling back to browser sign-in; remove the entry and add it again without the header.

Signed in, but no tools appear. Sign-in creates the agent; it does not grant tools. Check that the agent has a saved grant under Access in the workspace you approved, and that the connection itself does not show Needs sign-in or Needs attention.

The tool list is out of date after an access change. Reconnect from /mcp, or run /mcp reconnect all. Toolstile enforces the current grants on every call, so a stale list never keeps a removed permission working.

Tools from the wrong workspace. Each authorization is tied to one workspace, and switching workspaces in the dashboard does not move it. Add a second entry such as toolstile-team and authorize it for the other workspace. Confirm that a new browser approval actually happened for it.

Calls stop with a quota or billing message. The workspace has used its monthly operation allowance or forwarding is paused. A workspace owner can check Usage & billing.

A preferred account is unavailable. Toolstile stops rather than switching to another identity. Choose an available account under Shared accounts.

For other cases, see troubleshooting. When contacting support, include your Claude Code version and the exact error.

Remove Toolstile

Run claude mcp logout toolstile to clear stored credentials, then claude mcp remove toolstile (add --scope if you used a non-default scope). This only removes the local entry. To revoke access on Toolstile's side, choose Remove agent under Devices & agents.

Claude Code's own reference for these commands is Connect Claude Code to tools via MCP.

What is an MCP gateway? explains why one gateway URL can replace a per-project server list.
Codex, Cursor and Claude Desktop use the same gateway URL; give each app its own entry so it gets its own grant.
MCP allowlists compares Claude Code's local rules with gateway rules.