> ## Documentation Index
> Fetch the complete documentation index at: https://docs.budecosystem.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

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.

```mermaid theme={null}
flowchart TD
    A[Observed problem] --> B{Can the client connect?}
    B -->|No| C[Check endpoint, transport, token, and visibility]
    B -->|Yes| D{Is the capability listed?}
    D -->|No| E[Check virtual-server attachments and access scope]
    D -->|Yes| F{Does invocation succeed?}
    F -->|No| G[Check schema, backend auth, endpoint, and logs]
    F -->|Yes| H[Review result quality, prompt, resource, or skill]
```

## 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

| Symptom                               | Likely cause                                                         | What to check                                                                                |
| ------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Validation error                      | Arguments do not match the JSON Schema.                              | Required fields, types, allowed values, and unexpected properties.                           |
| Authentication or authorization error | Backend credentials are absent, expired, or under-scoped.            | Tool authentication configuration, secret values, API-token status, and backend permissions. |
| Connection error or timeout           | The target endpoint is unavailable or unreachable.                   | Endpoint URL, network reachability, DNS, TLS, timeout, and service health.                   |
| Backend error                         | The API accepted the request but could not process it.               | Backend logs, request mapping, headers, and the test input.                                  |
| Unexpected response                   | The endpoint or response mapping does not match the tool definition. | HTTP method, path parameters, headers, request body, and response filtering.                 |

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.

```mermaid theme={null}
flowchart LR
    A[Unexpected agent behavior] --> B[Inspect prompt or skill instructions]
    B --> C[Verify arguments and selected tools]
    C --> D[Verify attached resources and server catalog]
    D --> E[Test a minimal scenario]
    E --> F[Refine instructions or configuration]
```

## 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](./guides) and [Reference](./reference).