Add Basic MCP Support to OCSF Schema Server

[jasonbreimer]

Summary

Add minimal Model Context Protocol (MCP) support to the OCSF schema server to enable programmatic discovery of OCSF dictionaries, objects, and event classes by MCP‑compatible tools and clients.

This would expose a small, read‑only MCP surface over existing schema data without changing the underlying schema model or server behavior.

---

Motivation

As OCSF adoption grows, there is increasing interest in tooling that can dynamically explore and reason about the schema (e.g., IDE integrations, documentation assistants, AI tooling).

MCP has emerged as a lightweight, standardized way for clients to discover structured metadata and capabilities from servers. Adding basic MCP support would make the OCSF schema easier to consume programmatically while keeping the server implementation simple and stable.

---

Proposed Scope (Intentionally Minimal)

Initial MCP support would be limited to read‑only discovery of schema elements, such as:

• List available dictionaries
• List available objects
• List available event classes
• Fetch a specific dictionary, object, or event class definition by name

No mutation, persistence, or stateful behavior is proposed at this time.

[jasonbreimer]

Update to Issue #178 — Working POC Available

I have a working implementation. Branch and full README here:
https://github.com/jasonbreimer/ocsf-server/tree/MCP-Server

---

Why This Exists

Normalizing security events to OCSF requires deep familiarity with hundreds of
attributes, dozens of event classes, and dozens of reusable objects. Doing this
manually means:

• Constantly context-switching between the schema browser and your work
• Missing attributes you didn't know existed
• Inconsistent mappings across team members
• No way to validate your thinking quickly

This MCP server gives an AI assistant live, structured access to the OCSF schema.
You describe a raw event, ask the assistant to help map it to OCSF — it looks up
the right classes, attributes, and objects in real time and guides you through
normalization accurately and quickly. A workflow that previously took 30–60 minutes
of manual schema browsing now takes seconds.

---

Architecture

This is a lightweight Python sidecar. Zero changes to the OCSF server core.

┌──────────────────┐        ┌──────────────────┐        ┌──────────────────┐
│                  │  MCP   │                  │  HTTP  │                  │
│  AI Assistant    │◄──────►│  OCSF MCP Server │◄──────►│  OCSF Server     │
│  (Claude Desktop)│        │  (mcp_server.py) │        │  localhost:8080  │
│                  │        │                  │        │                  │
└──────────────────┘        └──────────────────┘        └──────────────────┘

The MCP server translates tool calls from the AI assistant into OCSF API requests
against the existing server. It doesn't touch schema logic, storage, or compilation
— it's purely a translation layer over the API that already exists.

---

What It Looks Like in Practice

Prompt: "I'm normalizing a Palo Alto firewall log. Fields: src_ip, dst_ip,
src_port, dst_port, protocol, action, bytes_sent, bytes_received, session_id.
What OCSF class should I use and how do I map these fields?"

Claude (with OCSF MCP connected):

1. Calls search_classes → finds network_activity (UID 4001)
2. Calls get_class → returns full attribute list
3. Maps fields: src_ip → src_endpoint.ip, dst_ip → dst_endpoint.ip,
   action → activity_id + action, etc.
4. Flags attributes you might have missed: severity_id, metadata, type_uid
5. Suggests the network_proxy profile if applicable

No browser. No copy-paste. No context-switching.

---

Tools Implemented

Tool	Description
search_attributes	Search the attribute dictionary by name, caption, or description
search_classes	Search event classes by name or keyword
get_class	Full definition of an event class including all attributes
search_objects	Search reusable objects (process, user, file, network_endpoint, etc.)
get_object	Full definition of an object including all attributes
list_categories	List all OCSF event categories
get_schema_version	Get the schema version currently loaded on the server

---

Why Not Just Use the Existing REST API?

Two reasons. First, MCP clients don't make raw HTTP calls — they need a
discoverable tool manifest. Second, the existing API returns full compiled JSON
per class, which overflows an LLM context window on anything substantial. The MCP
layer returns exactly what's useful for mapping decisions: field names, types,
requirement levels, constraints.

The export/schema alternative has similar limitations — the compiled schema is ~46MB, it goes stale when the schema version changes, and loading it wholesale into a context window isn't always practical.

---

Testing

The fastest way to see it is the MCP Inspector — the official MCP debugging tool,
no AI assistant required:

npx @modelcontextprotocol/inspector ~/ocsf/ocsf-mcp/run.sh

Open http://localhost:5173, call tools interactively, inspect raw
request/response JSON.

Claude Desktop config:

{
  "mcpServers": {
    "ocsf": {
      "command": "/path/to/ocsf-mcp/.venv/bin/python3",
      "args": ["/path/to/ocsf-mcp/mcp_server.py"],
      "env": {
        "OCSF_BASE_URL": "http://localhost:8080"
      }
    }
  }
}

---

Roadmap

• validate_event — validate a JSON event against the OCSF schema
• suggest_class — given an event description, suggest the best matching class
• diff_versions — compare attributes between schema versions
• Feature flag to disable the MCP endpoint for hosted deployments
• Contribute upstream ← this issue

---

Scope

Read-only. No mutation, no persistence, no stateful behavior. No changes to schema
compilation, storage, or server behavior. The MCP server is a sidecar that can
live in this repo under mcp/ or as a standalone project — happy to discuss what
makes more sense for the project.

Happy to demo this live or answer questions about the implementation.

[rmouritzen-splunk]

Instead of, or along side this, consider using the ocsf-schema-compiler (https://pypi.org/project/ocsf-schema-compiler/). Also:

• https://github.com/ocsf/ocsf-schema-compiler/
• And specifically this doc, which shows a good amount of detail about the compiler output: https://github.com/ocsf/ocsf-schema-compiler/blob/main/docs/diffs.md