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

Open Devices & agents, choose Connect an agent, and select your Agent app. Guided setup provides the same app selector under Connect your agent. Copy the displayed command, configuration, or endpoint and follow the sign-in instructions for your client. 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.

For a headless script, Connect an agent → Create a token instead opens Create a token for a script. Name the script, select or name its device, choose Token expiry, and choose Create token. Store the displayed token privately and configure the 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. You can also edit their pairing on the Access page. If you cannot configure access, ask a workspace administrator to grant it for this agent.

For limited access, leave Allow all current and future capabilities unchecked. Add the required tool or prompt names under Allowed names, or resource addresses under Allowed URIs / URI templates, one per line. Use the provider's documented capability names rather than guessing them. Empty allowed fields grant no capabilities.

For full access, check Allow all current and future capabilities. This includes supported tools, resources, and prompts added later. Entries under Explicitly blocked still win. The provider account's permissions also continue to apply. Review the scope and choose Save access. 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. Catalog checks count toward the selected workspace's allowance. Choose Finish when setup confirms the connection.

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.