> For the complete documentation index, see [llms.txt](https://docs.opshub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opshub.com/v7.235/manage/mcp/mcp-troubleshooting.md).
# Troubleshooting
### MCP logs
The space.vars.OIM MCP server logs all incoming MCP requests and tool invocations. These logs can be viewed and downloaded directly from the space.vars.OIM UI - go to the Global Log screen and switch on the **MCP Logs** toggle. Refer to [MCP Logs](/v7.235/manage/administrator/log-viewer.md#mcp-logs) in the Administration section for details on accessing, downloading, and configuring MCP logs.
#### What the logs contain
Each log entry follows this format:
```
[] - [User:] [ReqId:]
```
The `[User:]` and `[ReqId:]` prefixes identify the user who made the tool call and a unique correlation ID assigned to that call, which is useful for tracing a single call end-to-end when multiple calls are logged concurrently.
For example:
```
2026-08-13 10:38:26.570+05:30 DEBUG [boundedElastic-1] co.op.mc.McpToolRegistrar - [User:admin] [ReqId:448d8ff2-dab5-4da6-ba8a-24bdde8e57c9] Executing tool=get_schema with arguments={toolName=update_system}
2026-08-13 10:38:26.701+05:30 DEBUG [boundedElastic-1] co.op.mc.McpToolRegistrar - [User:admin] [ReqId:448d8ff2-dab5-4da6-ba8a-24bdde8e57c9] Successfully executed MCP tool: update_system, Tool Call Result: ...
```
Typical entries include:
* **Tool invocations**: Logged with prefix `Executing tool=` - shows the tool called and the arguments passed
* **Tool results**: Logged with prefix `Successfully executed MCP tool: ` - shows the result returned
> **Note**: Credential-like values (passwords, tokens, API keys, secrets) are not present in the logs as-is - they appear masked as `********`.
### Debugging
* **To verify MCP server started and tools are registered**: Search for `Registering MCP tool` - confirms the MCP server started and all tools are available.
* **To check if an MCP request is being processed**: Search for `Executing tool=` (e.g., `Executing tool=get_integrations_list`) - confirms the request reached the server and processing has begun.
* **To check the result of a processed request**: Search for `Successfully executed MCP tool: ` - confirms the request completed and returned a result.
* **To trace a single tool call end-to-end**: Search the log for its `[ReqId:]` correlation ID - this returns the request, the response, and any error logged for that call. If a tool call fails, the same correlation ID is also included in the error returned to the client.
* **To find failures**: Search for `ERROR` or `WARN` in the log.
***
### Common issues
* [AI assistant does not connect to MCP Server](#ai-assistant-does-not-connect-to-mcp-server)
* [Authentication failure](#authentication-failure)
* [Tool calls succeed but return unexpected results](#tool-calls-succeed-but-return-unexpected-results)
* [HTTPS / SSL certificate errors](#https--ssl-certificate-errors)
***
#### AI assistant does not connect to MCP server
**Symptom**: The AI client reports that it cannot connect to the MCP server, or no OpsHub tools appear.
**Resolution**:
1. Verify the MCP endpoint URL is correct: `/OpsHubWS/mcp`
2. Confirm the space.vars.OIM instance is running and accessible - open it in a browser to verify.
3. Check that no firewall or proxy is blocking the connection to the space.vars.OIM host and port.
4. In the MCP logs, check whether `Registering MCP tool` entries are present - if absent, the MCP server did not start correctly.
#### Authentication failure
**Symptom**: The AI client connects but operations return authentication or authorization errors.
**Resolution**:
1. Verify the username and password (or Base64-encoded `Authorization` header value) in your client configuration are correct.
2. Confirm the user account is a local space.vars.OIM user - LDAP and SAML accounts cannot authenticate via MCP.
3. Confirm the user has the required roles and permissions for the operations being attempted.
#### Tool calls succeed but return unexpected results
**Symptom**: The AI assistant invokes tools successfully but the data returned seems stale or incorrect.
**Resolution**:
* Add *"Do not use previously fetched data"* to your prompt. AI assistants may cache tool results within a conversation session, so this forces a fresh query to space.vars.OIM.
#### HTTPS / SSL certificate errors
**Symptom**: The MCP client reports an SSL certificate error when connecting to an HTTPS space.vars.OIM instance.
**Resolution**: Refer to the [HTTPS Configuration](/v7.235/manage/mcp/mcp-configuration.md#https-configuration) section for steps to trust your server's certificate in the MCP client environment.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.opshub.com/v7.235/manage/mcp/mcp-troubleshooting.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.