Skip to main content

MCP Server

N
Written by Nataliia Pukaliak

This documentation is for third-party developers implementing MCP (Model Context Protocol) clients to communicate with the Public MCP Server.

Table of Contents

Quick Start

The Public MCP Server implements the Model Context Protocol over HTTP using the streamable-http transport. All requests follow the JSON-RPC 2.0 protocol format.

Base URL: https://pubmcps.socprime.com

Endpoint: /mcp

Transport: streamable-http

Basic Request Structure

All requests must be sent to the /mcp endpoint:

POST https://pubmcps.socprime.com/mcp
Content-Type: application/json
Authorization: Bearer <your-token>
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_content_data",
    "arguments": {
      "content_id": "abc123"
    }
  }
}

Basic Response Structure

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"content_id\": \"abc123\", \"title\": \"Content Title\", ...}"
      }
    ],
    "structuredContent": {
      "result": {
        "content_id": "abc123",
        "title": "Content Title",
        "short_summary": "Summary...",
        "extended_summary": "Extended summary...",
        "decision_tree": "Decision tree...",
        "description": "Description..."
      }
    },
    "isError": false
  }
}

Authentication

All requests require a valid authorization token in the Authorization header.

The end-client organization can generate a token on the MCP Tokens page on the SOC Prime Platform. Refer to this guide to learn how to generate an MCP token. When using the get_content_data/search_content tools endpoints, the token will allow getting detection content that is currently available under the end-client organization's subscription.

Header Format

Authorization: Bearer <your-token>

Authentication Errors

HTTP Status

Error

Description

401

Missing authorization token

No token provided in the Authorization header

400

Invalid or expired authorization token

Token is provided but invalid, expired, or not found in the system

Example Request with Authentication 

curl -X POST https://pubmcps.socprime.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token-here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_content_data",
      "arguments": {
        "content_id": "abc123"
      }
    }
  }'

Rate Limiting

The server implements a token bucket rate limiting algorithm scoped by company. Each company has its own rate limit bucket.

Limits

  • Rate: 10 requests per minute

  • Burst capacity: 10 requests

  • Scope: Per company (extracted from authorization token)

Rate Limit Error

When rate limit is exceeded, the server returns HTTP status 200 with isError: true in the result:

HTTP Status: 200

Error Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Rate limit exceeded"
      }
    ],
    "isError": true
  }
}

Important: Always check the isError field in the result to detect rate limit errors or other types of errors. When isError is true, the request was not processed.

Available Tools

get_content_data

Retrieves detailed information about a specific content item by its ID.

Parameters

Parameter

Type

Required

Description

content_id

string

Yes

The unique identifier of the content to retrieve

Request Example

curl -X POST https://pubmcps.socprime.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token-here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_content_data",
      "arguments": {
        "content_id": "LBBwWxZrD2lE"
      }
    }
  }'

Response Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"content_id\": \"LBBwWxZrD2lE\", \"title\": \"Successful Overpass the Hash Attempt\", ...}"
      }
    ],
    "structuredContent": {
      "result": {
        "content_id": "LBBwWxZrD2lE",
        "title": "Successful Overpass the Hash Attempt",
        "short_summary": "**Summary:**\nThis detection rule flags successful Windows logons that use **Logon Type 9 (NewCredentials)**...",
        "extended_summary": "- **Purpose**: The rule identifies successful \"Overpass‑the‑Hash\" (Pass‑the‑Key) events...",
        "decision_tree": "## High‑Level Decision Tree (Conceptual Overview)...",
        "description": "Detects successful logon with logon type 9 (NewCredentials) which matches the Overpass the Hash behavior of e.g Mimikatz's sekurlsa::pth module."
      }
    },
    "isError": false
  }
}

Response when content not found

Returns empty content array and structuredContent.result as null when content ID doesn't exist:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "result": null
    },
    "isError": false
  }
}

Response Fields

The structuredContent.result object contains:

Field

Type

Description

content_id

string

The unique content identifier

title

string

The content title/name

short_summary

string or null

Brief summary of the content

extended_summary

string or null

Detailed extended summary

decision_tree

string or null

Decision tree information for analysts

description

string or null

Content description

When content is not found, structuredContent.result is null.

search_content

Search for content items by keywords and SIEM type. The search is scoped to the authenticated company.

Parameters

Parameter

Type

Required

Description

keywords

array of strings

Yes

List of keywords to search (1-10 keywords)

siem_type

string

Yes

SIEM type to filter by (see SIEM Types)

limit

integer

No

Number of results to return (1-5, default: 5)

Request Example

curl -X POST https://pubmcps.socprime.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token-here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search_content",
      "arguments": {
        "keywords": ["overpass", "hash", "logon"],
        "siem_type": "splunk",
        "limit": 5
      }
    }
  }'

Response Example

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"results\": [{\"content_id\": \"LBBwWxZrD2lE\", \"title\": \"Successful Overpass the Hash Attempt\", ...}], \"total\": 1}"
      }
    ],
    "structuredContent": {
      "result": {
        "results": [
          {
            "content_id": "LBBwWxZrD2lE",
            "title": "Successful Overpass the Hash Attempt",
            "description": "Detects successful logon with logon type 9 (NewCredentials) which matches the Overpass the Hash behavior of e.g Mimikatz's sekurlsa::pth module.",
            "short_summary": "**Summary:**\nThis detection rule flags successful Windows logons that use **Logon Type 9 (NewCredentials)**...",
            "extended_summary": "- **Purpose**: The rule identifies successful \"Overpass‑the‑Hash\" (Pass‑the‑Key) events...",
            "decision_tree": "## High‑Level Decision Tree (Conceptual Overview)...",
            "text": "index=* source=\"WinEventLog:Security\" AND (EventCode=\"4624\" AND LogonType=\"9\" AND LogonProcessName=\"seclogo\" AND AuthenticationPackageName=\"Negotiate\")",
            "siem_type": "splunk"
          }
        ],
        "total": 1
      }
    },
    "isError": false
  }
}

Response when no results found

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [],
    "structuredContent": {
      "result": null
    },
    "isError": false
  }
}

Response Fields

The structuredContent.result object contains:

Field

Type

Description

results

array

List of matching content items

total

integer

Total number of results found

ContentSearchItem Object:

Field

Type

Description

content_id

string

The unique content identifier

title

string

The content title/name

description

string or null

Content description

short_summary

string or null

Brief summary of the content

extended_summary

string or null

Detailed extended summary

decision_tree

string or null

Decision tree information for analysts

text

string

SIEM-specific query or rule text

siem_type

string

SIEM type (matches the requested filter)

When no results are found, structuredContent.result is null.

SIEM Types

The following SIEM types are supported by the search_content tool:

ala, splunk, qradar, humio, athena, hunters-sql-query, elasticsearch, graylog, opendistro-query, ala-rule, mdatp, devo, kafka, sumologic, snowflake, axon-ads-query, chronicle-query, logpoint, crowdstrike, es-eql, arcsight-keyword, fortisiem, rsa_netwitness, es-dsl, fireeye-helix, cribl-kql-query, exabeam-eql-query, sumologic-cse, elastic-esql-query, carbonblack, kibana, coralogix-lucene-query, securonix, carbonblack-edr, anomali-aql-query, xpack-watcher, elastalert, arcsight-esm, elasticsearch-rule, es-rule-eql, powershell, humio-alert, chronicle, splunk_alert, sumologic-cse-rule, open-ioc, opendistro-rule, axon-ads-rule, grep, s1-events, roota, cortex-xdr-xql-query, cortex-xql-query, limacharlie, sentinel-one-power-query, tanium-trs-query, sentinel-kql-yaml-rule, semgrep-yaml-rule, sysmon, qualys, exabeam-analytics-rule, exabeam-correlation-rule, coralogix-lucene-rule, s1-process, elastic-esql-rule, opensearch-json-rule, elk stack, arcsight, falco-yaml-rule, splunk-pack, csharp, datadog-logs, dnif, es-qs-lr, hedera, logiq, sql, sqlite, streamalert, kibana-ndjson, sentinel, hawk, humio-pack, ee-outliers, elastalert-dsl, netwitness-epl, splunkxml, stix

Error Handling

The server uses different HTTP status codes for authentication errors and returns tool execution errors within the JSON-RPC response.

HTTP Status Codes

Status Code

Description

200

Request processed (check isError field for tool execution errors)

401

Missing authorization token

400

Invalid or expired authorization token

Authentication Errors

Authentication errors return appropriate HTTP status codes.

Missing Token (HTTP 401):

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Missing authorization token"
  }
}

Invalid Token (HTTP 400):

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Invalid or expired authorization token"
  }
}

Tool Execution Errors

Tool execution errors (rate limits, validation errors) return HTTP status 200 with isError: true in the result.

Rate Limit Error (HTTP 200):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Rate limit exceeded"
      }
    ],
    "isError": true
  }
}

Validation Error (HTTP 200):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Invalid parameters: ..."
      }
    ],
    "isError": true
  }
}

Error Detection Flow

To properly handle errors in your client:

  1. Check HTTP status code:

    • 401 → No authorization token provided

    • 400 → Invalid or expired authorization token

    • 200 → Request processed, proceed to step 2

  2. For HTTP 200 responses, check if it's a JSON-RPC error:

    • If response has error field → JSON-RPC protocol error

    • If response has result field → Proceed to step 3

  3. For responses with result, check the isError field:

    • false → Tool executed successfully, check structuredContent.result for data

    • true → Tool execution failed (rate limit, validation error, etc.)

Response Format

All successful tool calls return a response with the following structure.

Response Object

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [...],
    "structuredContent": {
      "result": {...}
    },
    "isError": false
  }
}

Fields

Field

Type

Description

content

array

List of content blocks. Each block has type (usually "text") and text fields. The text field contains a JSON-serialized string of the result. Empty array when no data or error occurred.

structuredContent

object

Object containing a result field with the structured data. Use structuredContent.result to access the actual tool response.

structuredContent.result

object or null

The actual tool response data. null when content is not found or no results.

isError

boolean

false for successful executions, true for errors (rate limit, validation errors).

Content Blocks

The content array contains content blocks:

{
  "type": "text",
  "text": "{\"content_id\": \"abc123\", \"title\": \"Example\", ...}"
}

Important: The text field contains a JSON-serialized string of the result object. However, it is strongly recommended to use structuredContent.result instead, which provides the same data in a structured format without requiring deserialization.

Examples

Example 1: Get Content Data - Success

Request:

curl -X POST https://pubmcps.socprime.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token-here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_content_data",
      "arguments": {
        "content_id": "abc123"
      }
    }
  }'

Success Response (HTTP 200):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"content_id\": \"abc123\", \"title\": \"Example Title\", ...}"
      }
    ],
    "structuredContent": {
      "result": {
        "content_id": "abc123",
        "title": "Example Title",
        "short_summary": "Brief summary",
        "extended_summary": "Detailed summary",
        "decision_tree": "Decision tree",
        "description": "Description"
      }
    },
    "isError": false
  }
}

Example 2: Get Content Data - Not Found

Response (HTTP 200):

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [],
    "structuredContent": {
      "result": null
    },
    "isError": false
  }
}

Example 3: Search Content - Success

Request:

curl -X POST https://pubmcps.socprime.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token-here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_content",
      "arguments": {
        "keywords": ["mimikatz", "credential"],
        "siem_type": "splunk",
        "limit": 3
      }
    }
  }'

Success Response (HTTP 200):

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"results\": [...], \"total\": 1}"
      }
    ],
    "structuredContent": {
      "result": {
        "results": [
          {
            "content_id": "xyz789",
            "title": "Mimikatz Credential Dumping",
            "description": "Detects Mimikatz credential dumping activity",
            "short_summary": "Detection for Mimikatz...",
            "extended_summary": "Detailed analysis...",
            "decision_tree": "Decision tree...",
            "text": "index=windows EventCode=4688 CommandLine=\"*mimikatz*\"",
            "siem_type": "splunk"
          }
        ],
        "total": 1
      }
    },
    "isError": false
  }
}

Example 4: Search Content - No Results

Response (HTTP 200):

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [],
    "structuredContent": {
      "result": null
    },
    "isError": false
  }
}

Example 5: Missing Authorization Token

Error Response (HTTP 401):

{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32001,
    "message": "Missing authorization token"
  }
}

Example 6: Invalid Authorization Token

Error Response (HTTP 400):

{
  "jsonrpc": "2.0",
  "id": 6,
  "error": {
    "code": -32001,
    "message": "Invalid or expired authorization token"
  }
}

Example 7: Rate Limit Exceeded

Error Response (HTTP 200):

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Rate limit exceeded"
      }
    ],
    "isError": true
  }
}

Example 8: Invalid SIEM Type

Error Response (HTTP 200):

{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Invalid parameters: siem_type must be one of the supported SIEM types"
      }
    ],
    "isError": true
  }
}

Example 9: Invalid Keywords Count

Error Response (HTTP 200):

{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Invalid parameters: keywords list length must be between 1 and 10"
      }
    ],
    "isError": true
  }
}

Support

For issues or questions about the API, please contact the development team or refer to the MCP specification at https://modelcontextprotocol.io/

Did this answer your question?