Troubleshoot an MCP connection

On this page

To troubleshoot an MCP connection in Toolstile, check the selected workspace, the agent's access and the connection status first. Then look for a matching activity entry. Browser sign-in, agent authorization and sign-in to a connected service are separate: completing one does not complete the others.

Possible cause: Your Toolstile session has expired, the client authorization did not finish, or the device or agent authorization was revoked or expired.

Action: Sign in to Toolstile, then complete the client's authorization flow for the intended workspace. Check that the agent appears there and still has access. If you cannot access your Toolstile account, use account recovery with a saved recovery code or an available method shown there. Use client setup when reconnecting.

Possible cause: The remote MCP server requires sign-in, rejected its credentials, could not be reached or did not complete connection detection. “Needs attention” is a reason to investigate, not a precise diagnosis. “Not verified” means Toolstile has not yet confirmed the connection; it is not an error by itself.

Action: Check the server URL and authentication method. Complete sign-in for the selected account, or ask the account's contributor to update its credentials. Verify the connection again. Toolstile's managed service needs a public HTTPS MCP endpoint on port 443; it cannot connect to a process on your laptop or a private network. See connection and authentication steps.

A tool is missing or returns “access denied”

Possible cause: The agent has no grant for that MCP entry, the tool is blocked, the account is unavailable, the provider does not expose that tool to the selected account, or the authorization is paused.

Action: Check the agent's effective permissions in this workspace. In a team, ask someone who manages agent access to review that specific agent's grants and policy assignments. An explicit block wins over an allow or full-access grant. Full access includes supported tools, resources and prompts, including new ones the server adds, subject to blocks. Refresh the client's tool list after resolving access. Follow permissions for the detailed rules.

My preferred account is unavailable

Possible cause: Its approval was revoked, its contributor withdrew it or left the team, or its authentication needs attention.

Action: Open Shared accounts and choose an available approved account, or ask the contributor to reconnect it. You can explicitly choose Use workspace default after checking that default. Toolstile does not silently substitute another account. See shared accounts and handovers.

I see the wrong connections or workspace

Possible cause: The client was authorized for a different workspace, or you are looking at a different workspace in the dashboard. Personal and team catalogs are separate.

Action: Compare the client's Toolstile configuration and authorization with the intended workspace. Switching the dashboard workspace does not move an agent's authorization. Authorize the client for the correct workspace and grant it the intended MCP access. Use getting started to check the configuration.

For example, a “coding agent” authorized for your personal workspace will not see the team's shared MCP entry. Open the team workspace and check that agent's authorization there.

Forwarding is paused or the allowance is exhausted

Possible cause: The workspace reached its monthly operation allowance, its subscription no longer permits forwarding, or access depends on a policy or role unavailable on its current plan. A temporary request-rate limit can also reject requests.

Action: Ask a workspace owner to check Usage & billing, including usage, period end and payment status. Remaining operations do not override a payment pause; an active subscription does not override an exhausted allowance. After a plan change, an administrator may need to convert affected roles or policies. For a temporary rate limit, wait briefly before retrying. Read operations and billing for reset and counting rules. Paid options are available only when offered in the app.

Billing says the provider is unavailable

Possible cause: Toolstile could not confirm billing status with its billing provider. Forwarding can pause while that status is unavailable, even if the usage display shows operations remaining.

Action: A workspace owner can choose Refresh status on Usage & billing. If it remains unavailable, contact support with the time and workspace name. Wait for confirmation of any pending billing change before trying another change.

Verification works, but the tool call fails

Possible cause: Connection verification discovers the server's available tools, resources and prompts. It does not execute your chosen tool or prove that a particular client, account, permission or argument will work for that call.

Action: Use Test tool with your own authorized agent and review its permitted tools and arguments. This runs a real call and can change data; choose a read-only action where possible. Check the returned error and activity. A remote service can reject an otherwise permitted request because of its own permissions, limits or availability. Connection docs explain verification; permissions explain agent access.

My client cannot connect to the gateway

Possible cause: Its remote MCP transport or authorization support differs from the configured setup, or its configuration is incomplete.

Action: Check client setup, including the documented connection method and any version requirements. Record your client version and exact error. MCP support alone does not establish compatibility with every transport, authorization flow or capability. If the guide does not cover your setup, send those details to support.

Activity is visible, but request contents are missing

Possible cause: Activity normally contains metadata, not full arguments and results. Debug capture is off by default, may have stopped, may not include the agent and MCP involved, or may have expired.

Action: In Activity, the personal workspace owner or a team owner/admin can select the agents and MCPs to capture, then start a one-hour session. Starting capture does not run a tool or recover earlier traffic. Reproduce the issue, then stop capture. Continuing beyond the session requires an explicit extension. Captured contents are retained for up to 24 hours; activity metadata is retained for 30 days. Stopping capture stops new collection; it does not immediately delete stored captures. Capture limits can also leave results truncated or absent. Review the privacy policy before capturing sensitive traffic; automatic redaction may miss secrets.

Get help

Email support with the workspace name, approximate time and timezone, client and version, MCP label, and error text. Remove credentials, authorization codes and sensitive request contents before sending.