Diagnose common MCP Foundry configuration, discovery, connectivity, and governance problems.

​

Troubleshooting

Use this page to isolate problems from the outside in: confirm the server is published, verify the client identity and catalog, then inspect the capability configuration and backend dependency.

​

A virtual server is not visible in Playground or to a client

Check the following in order:

1. Confirm the virtual server was created or published successfully.
2. Verify that the client is connecting to the intended server endpoint and transport.
3. Check the server visibility, team assignment, and the identity used by the client.
4. Confirm the client’s API token or session is active and has the required scope.
5. Review Logs for authentication, authorization, or connection errors.

If the endpoint is visible but has an empty catalog, the connection is working; continue with the next section.

​

A tool, resource, prompt, or skill is missing

A capability must both exist in the catalog and be attached to the selected virtual server.

• Confirm you saved the capability and that it is active according to your deployment’s lifecycle settings.
• Open the virtual server and verify the capability is selected in its attachment list.
• Check visibility and team ownership for both the server and the capability.
• For a skill, verify its selected tools are also available through the server when the procedure requires them.
• Reopen Playground or reconnect the client so it refreshes the MCP catalog.

​

A tool call fails

Never address a tool-call failure by broadly increasing backend permissions. Start with logs and the specific failing request, then make the smallest correction needed.

​

Generated tools are incomplete or incorrect

1. Open Generation Jobs and inspect the job outcome.
2. Confirm the source is a valid, reachable OpenAPI document, API documentation page, or Postman collection.
3. For documentation URLs, prefer a direct JSON or YAML OpenAPI specification when one is available.
4. Verify that authentication requirements and the API base URL were represented correctly.
5. Review each generated schema and operation before attachment to a production server.
6. Regenerate or manually refine the affected tool, then test it in a sandbox server.

​

A resource cannot be read or contains stale content

• Verify the resource URL is reachable from the deployment, or check the saved inline content.
• Confirm the resource is attached to the virtual server and visible to the calling identity.
• Review the declared resource type and metadata.
• Update the source or inline content when policy or knowledge changes, then retest the resource read.

​

A prompt or skill does not behave as expected

For prompts, ensure every template variable has a declared argument and test with representative values. For skills, verify that the instructions identify the allowed tools, state guardrails and escalation criteria, and prescribe an answer format. Keep the skill’s selected tools and the virtual server’s attachments aligned.

​

Connected MCP server problems

• Verify the remote server URL, transport selection, and any required authentication configuration.
• Check that the remote server is healthy and reachable from MCP Foundry.
• Refresh or inspect the imported capability catalog after a connection change.
• If a command-line server is being wrapped, confirm its command, runtime dependencies, and permitted roots are available to the deployment.
• Use logs to distinguish a remote-server failure from a local authorization or routing problem.

​

When escalating an issue

Capture the virtual-server name, capability name, time of the request, client identity or token type (never the secret), request ID if available, error message, and relevant sanitized log entries. Include the expected behavior and a minimal reproduction using non-sensitive test data. For additional configuration workflows, see Guides and Reference.