Connect your first MCP server and agent

Start with one remote MCP server and one agent. You will add the server to Toolstile, authorize the agent in a workspace, and save an access grant. Finish by checking the permitted tool catalog. Running a tool is optional and requires a separate action.

For this walkthrough, picture a connection at https://mcp.example.com/mcp, a “coding agent”, and a device named “Work laptop”. The URL is a placeholder; use your provider's actual endpoint and choose names you will recognize later.

Before you start

You need a Toolstile account, an agent app that can connect to a remote MCP gateway using an available authentication method, and the provider's MCP server URL. Get that URL from the provider's MCP documentation or account settings. A normal website address or REST API URL may not be an MCP endpoint.

The server must be publicly reachable over HTTPS on port 443. Localhost, private-network servers, and stdio processes cannot be connected to the managed service. Have access to the provider account or its bearer token if required. In a team workspace, you may also need an administrator to approve the connection and grant agent access.

Create a Toolstile account or sign in, then use the workspace menu to select the workspace where you want to set up access.

Add the MCP server

1. Open MCP connections and choose Connect an MCP. In Guided setup, the equivalent action is Add an MCP under Connect an MCP.
2. Paste the provider's endpoint into MCP server URL. Leave the automatic settings in place unless the provider specifies otherwise.
3. If the provider supplies a bearer token, open Advanced options and enter the token value in Bearer token. Leave out the Bearer prefix; Toolstile adds it to the outgoing header.
4. Choose Connect. Toolstile attempts to detect the transport and authentication method.
5. If provider sign-in opens, review the account-replacement confirmation and choose Continue to provider. Complete the provider's approval flow and return to Toolstile. To retry later, use Sign in / reconnect on the connection.

Adding the server or signing in to it does not give an agent access. If the connection shows Needs attention, check the endpoint and authentication before continuing. The connection guide explains manual transport selection and OAuth client settings.

Connect your agent

An agent is an AI app or script that uses your MCP connections. Open Devices & agents, choose Connect an agent, and select your Agent app. Guided setup provides the same app selector under Connect your agent. Choose Copy to copy the displayed terminal command, file contents or connector URL, then follow the steps shown for your app. For Claude Code, open a terminal, paste the command and press Enter; then start Claude Code, type /mcp, press Enter and sign in. The client setup guide gives the app-specific steps.

You can also copy the gateway address from Settings → Endpoint. Use the displayed address exactly. It points your client at Toolstile; the provider's MCP URL belongs in MCP connections.

Start authorization from the agent app. In the browser:

1. Sign in to Toolstile if prompted.
2. Select the intended Workspace. This authorization uses that workspace's catalog and operation allowance.
3. Review the suggested agent and device names. Edit names lets you rename them or choose an existing device; otherwise, approval creates the needed records.
4. Choose Approve and complete any subsequent Allow connection consent screen.

Return to the dashboard and confirm that the agent appears in Devices & agents. In the example, you would see “coding agent” under “Work laptop”. Devices group agent connections; each agent is authorized separately. Changing the dashboard workspace later does not move that authorization or combine your personal and team catalogs. To use another workspace, configure a separately named client entry and authorize that entry for the other workspace, following your client's instructions.

If you have no AI app on this device, or your app or script cannot sign in through a browser, choose Create an agent token. It is in guided setup under Connect your agent, and in Devices & agents → Connect an agent. Enter an Agent name, select or name its device, choose Token expiry, and choose Create token. When you start from guided setup, setup selects the new agent and moves on to Give access. Store the displayed token privately. Copy configuration copies a remote MCP configuration that contains the token; otherwise configure the app or script to send it to the gateway as Authorization: Bearer <TOOLSTILE_AGENT_TOKEN>. This placeholder is not a real credential. The token identifies the script's agent; it is separate from any provider token you entered earlier.

Give access

New agents start without MCP access. In guided setup, select the connection and agent, then choose Configure access under Give access. This opens the Access page for that server and moves to the agent's column, even when the page is already open. If you cannot configure access, ask a workspace administrator to grant it for this agent.

For limited access, check the tools, resources and prompts the agent needs in its column. The list comes from the server itself, so you do not need to type names. Unchecked capabilities are not available.

For full access, check Everything, including ones added later at the top of the agent's column. This includes supported tools, resources, and prompts added later. Unchecking a single box afterwards blocks that capability, and blocks always win. The provider account's permissions also continue to apply. Review the scope and choose Save changes. See Permissions for the full rules.

Verify the permitted catalog

Once access is saved, guided setup checks the selected agent's permitted tool catalog. If the check fails, correct the connection or access settings and use Retry. A successful check means Toolstile could retrieve the catalog with that authorization. It does not run a tool or establish that every possible request will succeed. Checks don't use operations. While the check runs, setup shows its progress. When it passes, setup names the agent and the tools it may use. Choose Finish to close the guide; setup does not close on its own.

You can inspect the catalog separately from the connection's Test tool action: select your Agent, then choose Load permitted tools. An empty result may mean no tools were allowed, the provider exposes none, or blocks remove them. Resource-only or prompt-only access does not create tool access.

To check execution, select a tool, read its description and input requirements, and review Tool arguments (JSON). Choose Run test tool only when you intend to execute it. The call uses the selected agent's current account and permissions and may change provider data.

For more connection options, read Connect a remote MCP server. If the check fails or expected tools are missing, use Troubleshooting. Return to the documentation index for the setup overview.