ThreatByte-MCP Server

ThreatByte-MCP is a deliberately vulnerable, MCP-based case management server designed for training and demonstration. It mirrors a realistic SOC analyst workflow with a server-rendered UI and a real MCP server, enabling you to practice workflows with safe, contained exposure.

How to use

You will run two separate servers: the SOC web app for the user interface and the MCP server that provides the tools and agent runtime. The web app communicates with the MCP server through a server-side proxy to keep authentication consistent with your SOC session. To start using ThreatByte-MCP, first ensure both servers are running, then connect your MCP client to the MCP endpoint exposed by the stack.

How to install

Prerequisites you need on your machine:

• Python 3.8+ and a functioning Python virtual environment

• pip for installing Python dependencies

Follow these steps to install and run ThreatByte-MCP locally:

cd ThreatByte-MCP
python -m venv venv_threatbyte_mcp
source venv_threatbyte_mcp/bin/activate
pip install -r requirements.txt
python db/create_db_tables.py
python run_mcp_server.py
python run.py

Open in your browser: http://localhost:5001. MCP Server: http://localhost:5002/mcp

## Additional sections

Configuration and security notes: the web app proxies MCP calls and uses shared headers for authentication between the SOC app and the MCP server. Use environment variables TBMCP\_MCP\_SERVER\_TOKEN and TBMCP\_MCP\_SERVER\_URL to configure the MCP server connection. Keep API keys and tokens server-side only and never expose them to the browser.

Sample data can be populated to accelerate testing. The launcher provides a script to generate users, cases, notes, and files. Passwords for seeded users are Password123!. Use the following command to populate the data after initial setup.

python db/populate_db.py --users 8 --cases 20 --notes 40 --files 20

## Troubleshooting and notes

If you encounter connectivity issues between the SOC UI and the MCP server, verify the MCP URL and token are correctly configured on both sides. Check the server logs for authentication headers like X-TBMCP-Token and X-TBMCP-User to ensure the proxy is transmitting the right session data.

This setup intentionally includes vulnerabilities for training purposes. Do not expose it to the public internet. Review and practice with proper containment and access controls in a controlled environment.

## Available tools

### cases.create

Create a new case with metadata, assignees, and initial context.

### cases.list

List cases visible to the current user.

### cases.list\_all

List all cases in the system (may include restricted data).

### cases.get

Retrieve a specific case by ID.

### cases.rename

Rename an existing case.

### cases.set\_status

Update a case status.

### cases.delete

Delete a case.

### notes.create

Add a note to a case.

### notes.list

List notes for a case.

### notes.update

Update an existing note.

### notes.delete

Remove a note.

### files.upload

Upload a file artifact to a case in base64.

### files.list

List files attached to a case.

### files.get

Retrieve a file as base64.

### files.read\_path

Read a file by path within the storage.

### indicators.search

Search indicators across cases.

### agent.summarize\_case

Summarize a case for reporting by the agent.

### agent.run\_task

Execute an agent task against a case.

### tools.registry.list

List registered MCP tools in the registry.

### tools.builtin.list

List built-in MCP tools.

### tools.registry.register

Register a new tool in the MCP registry.

### tools.registry.delete

Remove a tool from the MCP registry.