FAQ and Troubleshooting

This page collects the most common and most practical troubleshooting scenarios in the current version. We recommend using it together with Logs and Diagnostics.

What to do when a service will not connect

Check the following in order:

1. Whether the service configuration is complete
2. Whether the correct service type is selected
3. For STDIO services, whether the command, arguments, environment variables, and working directory are correct
4. For remote services, whether the URL and request headers are correct
5. Whether OAuth authorization is required
6. Whether the current network environment is reachable

The recommended order is: "check the configuration first, then the authorization, then the logs."

Why not just configure MCP in each AI client directly

There are four practical problems:

• The same MCP has to be configured repeatedly
• Every client has to spin up its own processes
• It is hard to observe calls and errors in one place
• For long-term workflows, converting to a Skill makes it easier to control cost through on-demand loading

If you are just testing temporarily, configuring the client directly may be enough; if you want stable long-term usage, MCP2Skill is the better fit.

When to generate a Skill vs. when to use the gateway

You can decide like this:

• To save Tokens, turn high-frequency MCP tools into on-demand loadable capabilities, and serve an AI Agent: prefer Generate a Skill
• To stay compatible with multiple AI clients and reuse one configuration across them: prefer Use the gateway
• To have both: organize your MCP first, then keep both the Skill path and the gateway path

You can remember it in one sentence:

• The Skill path solves Token usage and workflow efficiency
• The gateway path solves integration compatibility and unified management

The service status is normal, but tools are not showing

Check first:

• Whether the tool list on the service detail page is actually empty
• Whether the service has just connected and the tools have not been fetched yet
• Whether OAuth authorization needs to be completed first
• Whether the tools have been disabled at the service level

If you cannot see tools in a workspace, also check whether they have been disabled at the workspace level.

External clients cannot reach the endpoint

Common causes include:

• The wrong endpoint was copied
• The port was changed but the client was not updated
• The API Key is enabled, but the client does not include it
• You are using a workspace endpoint, but the target tool is not actually in that workspace
• Remote access is not configured correctly for your use case

The safest approach is to verify with the ALL endpoint first, then narrow down step by step.

What to do when OAuth authorization fails

Check along these lines:

• Whether the remote service actually supports the authorization flow
• Whether the system browser opens correctly
• Whether authorization has completed but the status has not refreshed
• Whether the authorization has expired
• Whether you need to re-authorize or revoke and start over

After completing authorization, always check the tool list again instead of only looking at the "Authorized" status.

Import reports no configuration file detected

This usually means:

• The application has not left a configuration file on the current machine
• The configuration file path does not match the detection locations MCP2Skill currently supports
• The target application has no MCP configuration yet

In that case, switch to:

• Import from clipboard
• Import from a local file

Import succeeded, but the service is still unavailable

Import only brings the configuration in; it does not automatically fix the runtime environment.

You still need to check:

• Whether local command dependencies are installed
• Whether the environment variables are still valid
• Whether the remote address is still reachable
• Whether OAuth authorization needs to be completed separately

Some tools are missing from a workspace

There are usually three kinds of causes:

• The tool has been disabled at the service level
• The tool has been disabled at the workspace level
• The corresponding service is not currently running

We recommend first confirming on the service detail page that the tool's source is available, then going back to the workspace to investigate.

The JSON configuration copies fine, but the client still reports errors

Confirm first:

• Whether the endpoint in the JSON uses the current, latest port
• Whether the API Key matches the current settings
• Whether the client has refreshed or reloaded the configuration
• Whether you copied a single-service configuration or a workspace configuration

If you have just regenerated the API Key, this item is especially easy to miss.

Why does unified management lower resource usage on my machine

Because you no longer need multiple AI clients to each maintain and start the same batch of MCP.

Centralizing in MCP2Skill usually means:

• Configuration is maintained in one place
• Runtime is managed in one place
• Debugging is observed in one place

This does not mean resource usage drops linearly in every scenario, but it usually significantly reduces the waste of "duplicated startups, duplicated maintenance, and duplicated troubleshooting."

Skills page does not show newly installed content

Check first:

• Whether the correct directory is configured under Settings > AI Agents
• Whether the Skill was actually installed into that directory
• Whether the directory contains a SKILL.md
• Whether the Skills page has been refreshed

If it still does not work, verify the generated output using "Export to directory" first, then check the installation target.

Too many logs, not sure where to look first

The recommended minimal troubleshooting path is:

1. Look at the call log of the most recent failure first
2. Then look for keywords in the service logs
3. Then go back to the corresponding service, workspace, or settings page to fix it

Do not read all the logs from the start, or you will easily be drowned in noise.

What to do when you still cannot pinpoint the problem

If you have gone through all the paths above and still cannot find the cause, gather at least the following information:

• Which page or step the problem occurs on
• Which MCP service or which workspace is involved
• Whether the API Key is enabled
• Whether it is a remote service
• The time and error direction of the most recent failure on the logs page

With this, both self-diagnosis and handing the issue over to someone else will be much more efficient.

Back to reading

• To revisit the integration flow: see Quick Start
• To learn how to use the logs page: see Logs and Diagnostics
• To return to service management: see MCP Service Management