Troubleshoot MCP access to ITSI episode data

Use this decision tree to isolate where the failure occurs before moving into the detailed scenarios below.

Use this decision tree to isolate where the failure occurs before moving into the detailed scenarios below. Run the checks in order. Stop at the first failed check, apply the recommended resolution, and then retest the direct MCP workflow.

Step Question If yes If no
1 Is Splunk MCP Server installed and reachable at /services/mcp? Continue to step 2. Install or enable Splunk MCP Server, verify network access, and retry tools/list.
2 Do SA-ITOA_* tools appear in MCP Server? Continue to step 3. Register the ITSI tools from the Manage Apps page, then verify /services/mcp_tools?external_app_id=SA-ITOA.
3 Can you call SA-ITOA_get_episodes directly through MCP? Continue to step 4. Check encrypted token setup, tool enablement, ITSI health, and user capabilities.
4 Can the same identity access the target episode directly through the ITSI REST endpoint? Continue to step 5. Fix Splunk role, ITSI role, object-level access, or episode availability before troubleshooting the MCP client.
5 Does the requested data domain exist for the episode? Continue to step 6. Use a different tool or adjust the prompt. Not every episode has external links, similar episodes, or stored summarization.
6 Do direct tool calls return incomplete or generic answers? Use more precise tool calls and validate one domain at a time, such as impacted objects, external links, or similar episodes. Review timeout, row-limit, rate-limit, and Splunk search performance issues.

Quick diagnostic commands

Use these commands to confirm the most common breakpoints in the path from MCP clients to ITSI.

SHELL 
# 1. Confirm MCP Server responds and lists tools.
curl --request POST \
  --url https://<splunk_url>:8089/services/mcp \
  --header 'authorization: Bearer <encrypted_token>' \
  --header 'content-type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'
# 2. Confirm ITSI tools are registered in Splunk MCP Server.
curl -k -u admin \
  "https://<splunk_url>:8089/services/mcp_tools?external_app_id=SA-ITOA&output_mode=json"
# 3. Confirm a direct ITSI episode-list call works through MCP.
curl --request POST \
  --url https://<splunk_url>:8089/services/mcp \
  --header 'authorization: Bearer <encrypted_token>' \
  --header 'content-type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "SA-ITOA_get_episodes",
      "arguments": {
        "lookback": "24h",
        "count": 10,
        "sort_by": "recent"
      }
    }
  }'
# 4. Confirm the target episode exists and is accessible directly in ITSI.
curl -k -u <user> \
  "https://<splunk_url>:8089/servicesNS/nobody/SA-ITOA/event_management_interface/episode_details/<episode_id>"

ITSI tools do not appear in MCP Server

Symptoms: ITSI tools are missing from the MCP Server UI, tools/list does not show SA-ITOA_* tools, or the MCP tools endpoint returns an empty result for ITSI.

Example error response:

JSON 
{
  "tools": [],
  "total": 0
}

Validate registration state:

SHELL 
curl -k -u admin \
  "https://<splunk_url>:8089/services/mcp_tools?external_app_id=SA-ITOA&output_mode=json"

Resolution:

  • Register the tools from the Manage Apps page by finding SA-ITOA and clicking Register MCP Tools.
  • After registration, open the Splunk MCP Server app and click Enable all tools near the SA-ITOA section.

Optional REST validation:

SHELL 
# Register ITSI MCP tools from the SA-ITOA context.
curl -k -u admin \
  -X POST "https://<splunk_url>:8089/services/mcp/tool_registration" \
  -H "content-type: application/json" \
  --data '{"app_name":"SA-ITOA"}'
# Verify that ITSI tools are now registered.
curl -k -u admin \
  "https://<splunk_url>:8089/services/mcp_tools?external_app_id=SA-ITOA&output_mode=json"

If the tools still do not appear, confirm that ITSI 5.0.1 or later is installed, Splunk MCP Server is healthy, and the registration identity has the required capability to register app tools.

Tool calls return permission or authorization errors

Symptoms: Tool calls return 401, 403, or an MCP authorization error. The same user may also be unable to open the episode directly in ITSI.

Example error responses:

JSON 
{
  "error": "Unauthorized",
  "message": "Missing or invalid bearer token"
}
JSON 
{
  "messages": [
    {
      "type": "ERROR",
      "text": "User does not have permission to access ITSI episode data"
    }
  ]
}

Validate token and tool access:

SHELL 
curl --request POST \
  --url https://<splunk_url>:8089/services/mcp \
  --header 'authorization: Bearer <encrypted_token>' \
  --header 'content-type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/list",
    "params": {}
  }'

Resolution commands:

SHELL 
# Verify that the same identity can access the episode directly through the ITSI endpoint.
curl -k -u <user> \
  "https://<splunk_url>:8089/servicesNS/nobody/SA-ITOA/event_management_interface/episode_details/<episode_id>"
# Recreate or rotate the MCP encrypted token if the token is expired or invalid.
# Use the MCP Server token management UI or the approved token creation workflow for your environment.
# Retry the MCP call with the refreshed token.
curl --request POST \
  --url https://<splunk_url>:8089/services/mcp \
  --header 'authorization: Bearer <new_encrypted_token>' \
  --header 'content-type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "SA-ITOA_get_episode_details",
      "arguments": {
        "episode_id": "<episode_id>"
      }
    }
  }'

If access fails through the direct ITSI endpoint, update the user's Splunk role, ITSI role, and object-level access before retrying from MCP.

MCP clients return incomplete or unexpected episode data

Symptoms: An MCP client returns partial results, omits impacted services or external links, selects the wrong episode, or answers with generic guidance instead of ITSI data.

Example error or partial response:

JSON 
{
  "episode_id": "76b1ebc7-63e0-4677-800f-94cbf7b2ced3",
  "linked_tickets": [],
  "reference_links": []
}
JSON 
{
  "error": "invalid_request",
  "message": "Missing required argument: episode_id"
}

Validate the specific ITSI data domain directly:

SHELL 
# Episode details
curl -k -u admin \
  "https://<splunk_url>:8089/servicesNS/nobody/SA-ITOA/event_management_interface/episode_details/<episode_id>"
# Impacted objects
curl -k -u admin \
  "https://<splunk_url>:8089/servicesNS/nobody/SA-ITOA/event_management_interface/episode_details/<episode_id>/impacted_objects"
# External links
curl -k -u admin \
  "https://<splunk_url>:8089/servicesNS/nobody/SA-ITOA/event_management_interface/episode_details/<episode_id>/external_links"

Resolution commands and prompt guidance:

SHELL 
# Use a precise MCP call for the data domain you need.
curl --request POST \
  --url https://<splunk_url>:8089/services/mcp \
  --header 'authorization: Bearer <encrypted_token>' \
  --header 'content-type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 8,
    "method": "tools/call",
    "params": {
      "name": "SA-ITOA_get_impacted_objects",
      "arguments": {
        "episode_id": "<episode_id>"
      }
    }
  }'

When using a natural-language MCP client, ask for one data domain at a time. For example: "Get impacted objects for ITSI episode <episode_id>" or "Get external links for ITSI episode <episode_id>."

Episode summarization is missing

Symptoms: The summarization tool returns no summary, returns 404, or indicates that summarization is unavailable for the episode.

Example error responses:

JSON 
{
  "status": "not_found",
  "message": "No summarization found for episode"
}
JSON 
{
  "episode_id": "<episode_id>",
  "summarization": null,
  "access_restricted": false
}

Validate summarization directly:

SHELL 
curl -k -u admin \
  "https://<splunk_url>:8089/servicesNS/nobody/SA-ITOA/event_management_interface/episode_details/<episode_id>/summarization"

Resolution commands:

SHELL 
# If summarization is unavailable, continue the investigation with the other episode tools.
curl --request POST \
  --url https://<splunk_url>:8089/services/mcp \
  --header 'authorization: Bearer <encrypted_token>' \
  --header 'content-type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 9,
    "method": "tools/call",
    "params": {
      "name": "SA-ITOA_get_episode_details",
      "arguments": {
        "episode_id": "<episode_id>"
      }
    }
  }'
curl --request POST \
  --url https://<splunk_url>:8089/services/mcp \
  --header 'authorization: Bearer <encrypted_token>' \
  --header 'content-type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 10,
    "method": "tools/call",
    "params": {
      "name": "SA-ITOA_get_similar_episodes",
      "arguments": {
        "episode_id": "<episode_id>"
      }
    }
  }'

If summaries are expected, configure Event iQ Diagnose and follow the Event iQ documentation to enable and generate summarization data. Confirm that Event iQ Episode Summarization is enabled, the summary generation job has completed, and the requesting identity can access the referenced ITSI objects.

Tool responses are slow or time out

Symptoms: MCP calls time out, return a generic failure, or large episode queries return slowly.

Example error responses:

JSON 
{
  "jsonrpc": "2.0",
  "id": 11,
  "error": {
    "code": -32001,
    "message": "Tool execution timed out"
  }
}
JSON 
{
  "error": "rate_limit_exceeded",
  "message": "Too many MCP tool calls in a short period"
}

Validate with a smaller request:

SHELL 
curl --request POST \
  --url https://<splunk_url>:8089/services/mcp \
  --header 'authorization: Bearer <encrypted_token>' \
  --header 'content-type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 12,
    "method": "tools/call",
    "params": {
      "name": "SA-ITOA_get_episodes",
      "arguments": {
        "lookback": "1h",
        "count": 5,
        "sort_by": "recent"
      }
    }
  }'

Resolution commands:

SHELL 
# Check that Splunk can run a small episode search promptly.
curl -k -u admin \
  "https://<splunk_url>:8089/servicesNS/nobody/SA-ITOA/event_management_interface/episode_details?lookback=1h&count=5&sort_by=recent"
# Retry with narrower arguments before increasing lookback or count.
curl --request POST \
  --url https://<splunk_url>:8089/services/mcp \
  --header 'authorization: Bearer <encrypted_token>' \
  --header 'content-type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 13,
    "method": "tools/call",
    "params": {
      "name": "SA-ITOA_get_episodes",
      "arguments": {
        "lookback": "1h",
        "severity": "4",
        "count": 5,
        "sort_by": "recent"
      }
    }
  }'

If smaller requests succeed, reduce lookback, lower count, add a severity filter, avoid multi-tool prompts, and review Splunk search health, indexer health, MCP timeout settings, row limits, and rate limits.