---

name: traceix-mcp
description: Use this guide when operating the Traceix MCP server through Model Context Protocol clients, selecting Traceix MCP tools, reading Traceix MCP resources, uploading base64-encoded files with filenames for malware/file analysis, polling asynchronous Traceix jobs, investigating SHA-256 hashes, generating YARA rules, running CAPA, EXIF, AV, and full-upload workflows. Favor traceix_full_file_upload by default for broad file-analysis requests unless the user explicitly asks for a narrower Traceix result.
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

# Traceix MCP Agent Guide

## Authority and Scope

Use this skill when interacting with the Traceix MCP server.

This guide is authoritative for Traceix-specific behavior:

* which Traceix MCP tool to call
* what inputs each Traceix tool requires
* when to use full analysis versus narrow analysis
* how to handle Traceix async jobs
* how to handle Traceix credentials
* how to treat `traceix://` resources
* how to report Traceix results

Use the official Model Context Protocol documentation for protocol-level behavior that is not Traceix-specific, including MCP concepts, tool invocation, resource reading, transports, lifecycle, authorization, security, and schema behavior.

## Official MCP Documentation References

Agents SHOULD use these references when they need MCP protocol details:

* MCP introduction: `https://modelcontextprotocol.io/docs/getting-started/intro`
* MCP specification index, version 2025-06-18: `https://modelcontextprotocol.io/specification/2025-06-18`
* Architecture: `https://modelcontextprotocol.io/specification/2025-06-18/architecture`
* Base protocol overview: `https://modelcontextprotocol.io/specification/2025-06-18/basic`
* Lifecycle: `https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle`
* Transports: `https://modelcontextprotocol.io/specification/2025-06-18/basic/transports`
* Authorization: `https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization`
* Server tools: `https://modelcontextprotocol.io/specification/2025-06-18/server/tools`
* Server resources: `https://modelcontextprotocol.io/specification/2025-06-18/server/resources`
* Server prompts: `https://modelcontextprotocol.io/specification/2025-06-18/server/prompts`
* Schema reference: `https://modelcontextprotocol.io/specification/2025-06-18/schema`
* MCP Inspector: `https://modelcontextprotocol.io/docs/tools/inspector`
* MCP debugging guide: `https://modelcontextprotocol.io/docs/tools/debugging`
* Complete documentation index for LLMs: `https://modelcontextprotocol.io/llms.txt`

Use the MCP docs to resolve protocol questions. Use this Traceix guide to resolve Traceix workflow questions.

## MCP Concepts for Traceix Agents

MCP exposes capabilities through a client-server protocol.

For Traceix:

* **Host**: the AI application or agent environment.
* **MCP client**: the connector inside the host that talks to the Traceix MCP server.
* **MCP server**: the Traceix service exposing tools and resources.
* **Tools**: executable operations the agent may call, such as upload, scan, classify, poll, or lookup.
* **Resources**: read-oriented context identified by URIs, such as `traceix://skill` or `traceix://docs/agent-guide`.
* **Prompts**: reusable MCP prompt templates. This Traceix server guide does not rely on prompts unless the server explicitly exposes them.
* **Transport**: the connection mechanism. The Traceix server is expected to use Streamable HTTP at `https://mcp.traceix.com/mcp`.

Protocol-level tool discovery happens through MCP tool listing, commonly `tools/list`. Protocol-level tool execution happens through MCP tool calling, commonly `tools/call`. Do not treat the root HTTP page, `/skill`, or `traceix://` resources as substitutes for MCP tool invocation.

## Core Directive

Favor full Traceix analysis by default.

When the user asks to analyze, inspect, scan, investigate, check, classify, triage, review, or run Traceix on a file, use `traceix_full_file_upload` unless the user explicitly asks for a narrower action.

Use a single-purpose Traceix tool only when the user clearly asks for a specific artifact, such as only a hash, only a YARA rule, only AV results, only CAPA, only EXIF, or only classification.

Do not upload arbitrary local files. Only upload files the user explicitly selected, attached, provided, or approved.

Never invent API keys, tokens, filenames, file contents, SHA-256 hashes, job UUIDs, tool outputs, resource contents, or analysis results.

## MCP Connection Reference

Expected Traceix MCP endpoint:

`https://mcp.traceix.com/mcp`

Expected transport:

Streamable HTTP.

When an MCP client is available:

1. Connect to the MCP endpoint.
2. Initialize the MCP session according to the MCP transport and lifecycle specification.
3. Discover server capabilities and tools through MCP.
4. Read Traceix resources only when read context is needed.
5. Invoke Traceix tools only for actions.

Do not scrape the root page as the API. Do not infer tool schemas from the root page when MCP tool discovery is available.

## Tool Versus Resource Rule

Use MCP tools for actions.

Use MCP resources for read-only context.

Action examples requiring tools:

* register a user
* log in
* retrieve an API key
* upload a file
* classify a file
* calculate a file hash
* generate a YARA rule
* start CAPA extraction
* start EXIF extraction
* start AV scanning
* poll job status
* search by SHA-256 hash

Read-only examples suitable for resources:

* read this guide from `traceix://skill`
* read the Traceix agent guide from `traceix://docs/agent-guide`
* read existing state exposed by a `traceix://` resource, if the server provides it

Do not treat a `traceix://` resource URI as an upload target or mutation endpoint unless the server explicitly exposes a tool that accepts that URI for that action.

## Default Tool Selection

For broad file-analysis requests, use:

`traceix_full_file_upload`

Use narrower tools only when the user explicitly narrows the request.

Examples of broad requests that should trigger `traceix_full_file_upload`:

* analyze this file
* scan this file
* inspect this binary
* check this sample
* investigate this file
* classify this file
* tell me what this file is
* is this malicious
* run Traceix on this
* get a full report
* do a complete analysis
* triage this sample

Examples of narrow requests that should not trigger full upload:

* get the file hash
* generate only a YARA rule
* run only AV
* run only CAPA
* extract only EXIF
* classify only
* check this SHA-256
* get AV results for this hash

If the request is ambiguous between broad analysis and a narrow artifact, choose `traceix_full_file_upload`.

## File Upload Input Contract

All Traceix file-upload tools accept only base64-encoded file uploads with a filename.

Required inputs for every Traceix file-upload tool:

* `filename`
* `file_base64`
* `api_key`

Example upload shape:

```json
{
  "filename": "sample.exe",
  "file_base64": "<BASE64_ENCODED_FILE_BYTES>",
  "api_key": "<TRACEIX_API_KEY>"
}
```

The MCP server decodes `file_base64` into a temporary server-side file, uploads that temporary file to Traceix, and then deletes the temporary file.

Mounted `file_path` uploads are not supported by the current Traceix MCP server contract.

Do not pass:

* `file_path`
* local filesystem paths
* connector-mounted paths
* raw binary bytes
* URLs instead of file content

If the available MCP client or connector exposes only `file_path`, do not call the upload tool. Report that the current Traceix MCP server requires `filename` and `file_base64`.

## Upload Validation Rules

For upload tools, always provide all three fields:

* `filename`
* `file_base64`
* `api_key`

Do not provide partial file input.

Do not invent a filename. Use the original filename when known.

Do not invent base64 content. Use only base64 content derived from a file the user explicitly selected, attached, provided, or approved.

If `filename` is missing, ask for the original filename.

If `file_base64` is missing, ask for the base64-encoded file content or for the user to provide the file through a workflow that can supply base64 content.

If the input is a local path, do not pass it as `file_path`. Convert the approved file to base64 only if the execution environment has legitimate access to the file and the user approved that file for upload.

## Credentials

Use a Traceix user token for user/account tools.

Use a Traceix API key for file-analysis and hash-analysis tools.

Token-based tools:

* `traceix_user_whoami`
* `traceix_user_get_api_key`

API-key-based tools:

* `traceix_search_sha_hash`
* `traceix_upload_and_classify`
* `traceix_get_file_hash`
* `traceix_generate_yara_rule`
* `traceix_get_yara_rule_by_hash`
* `traceix_start_capa_extraction`
* `traceix_start_exif_extraction`
* `traceix_check_job_status`
* `traceix_start_av_scan`
* `traceix_get_av_scan_status`
* `traceix_get_av_scan_by_hash`
* `traceix_full_file_upload`
* `traceix_full_file_upload_status`

If the user does not have an API key, guide them through login and API-key retrieval.

Do not expose secrets in final answers. Redact tokens and API keys unless the user explicitly asks to see a value that was already returned to them by the tool.

## User Onboarding Workflow

### New User

Use this sequence:

1. `traceix_register_user`
2. `traceix_user_login`
3. `traceix_user_get_api_key`
4. Use the returned API key for analysis tools

### Existing User

Use this sequence:

1. `traceix_user_login`
2. `traceix_user_get_api_key`
3. Use the returned API key for analysis tools

### Account Inspection

Use:

`traceix_user_whoami`

when the user asks about their Traceix account, plan, limits, token status, or authenticated identity.

## Default Full File Analysis Workflow

Use `traceix_full_file_upload` for default file analysis.

Required input:

* `filename`
* `file_base64`
* `api_key`

`traceix_full_file_upload` starts the primary Traceix file-analysis pipeline:

* file hash calculation
* malware classification
* YARA rule generation
* CAPA extraction
* EXIF extraction
* AV scanning

CAPA, EXIF, and AV may return asynchronous job UUIDs rather than immediate final results.

After calling `traceix_full_file_upload`, inspect the returned `async_jobs` field.

Use:

`traceix_full_file_upload_status`

to poll all available async job UUIDs together.

Use:

`traceix_check_job_status`

for CAPA and EXIF jobs.

Use:

`traceix_get_av_scan_status`

for AV jobs.

If a job is still pending, report the current status and UUID. Do not fabricate final output.

## Narrow File Workflows

Use narrow tools only when the user explicitly asks for a specific result.

All narrow file-upload tools require:

* `filename`
* `file_base64`
* `api_key`

### File Hash Only

Use:

`traceix_get_file_hash`

when the user asks only for the file hash.

### Classification Only

Use:

`traceix_upload_and_classify`

when the user asks only for Traceix classification or malware classification.

### YARA Only

Use:

`traceix_generate_yara_rule`

when the user asks only to generate a YARA rule from a file.

Use:

`traceix_get_yara_rule_by_hash`

when the user provides a SHA-256 hash and asks for an existing YARA rule.

### CAPA Only

Use:

`traceix_start_capa_extraction`

when the user asks only for CAPA extraction.

Then poll with:

`traceix_check_job_status`

### EXIF Only

Use:

`traceix_start_exif_extraction`

when the user asks only for EXIF extraction.

Then poll with:

`traceix_check_job_status`

### AV Only

Use:

`traceix_start_av_scan`

when the user asks only for an AV scan of a file.

Then poll with:

`traceix_get_av_scan_status`

Use:

`traceix_get_av_scan_by_hash`

when the user provides a SHA-256 hash and asks for existing AV results.

## Hash Investigation Workflow

When the user provides a SHA-256 hash rather than a file, do not upload anything.

Validate that SHA-256 values are 64-character hexadecimal strings before calling hash tools.

Use this sequence for broad hash investigation:

1. `traceix_search_sha_hash`
2. `traceix_get_yara_rule_by_hash`
3. `traceix_get_av_scan_by_hash`

Use only the specific hash tool if the user asks for a narrow hash-based lookup.

If the user provides a non-SHA-256 value, ask for a valid SHA-256 or clarify whether they want to upload a file instead.

## Async Job Handling

Some Traceix tools return a UUID and status instead of final results.

CAPA and EXIF jobs:

* start with `traceix_start_capa_extraction` or `traceix_start_exif_extraction`
* poll with `traceix_check_job_status`

AV jobs:

* start with `traceix_start_av_scan`
* poll with `traceix_get_av_scan_status`

Full upload jobs:

* start with `traceix_full_file_upload`
* poll with `traceix_full_file_upload_status`

When polling, preserve and reuse the UUIDs returned by the previous tool call.

If the job is pending, report:

* job type
* UUID
* current status
* next polling tool to use

Do not claim analysis is complete until the status endpoint returns completed results.

## `traceix://` Resource Behavior

The MCP server may expose this guide as:

`traceix://skill`

or:

`traceix://docs/agent-guide`

Read this guide when unsure how to select Traceix tools.

Use `traceix://` resources for read-oriented context only.

Do not treat `traceix://` resources as file-upload or mutation endpoints unless the MCP server explicitly exposes an action tool that accepts a `traceix://` action URI.

Prefer explicit MCP tools over generic action routers when available.

## Recommended `traceix://` URI Map

Use these resource URI conventions when available:

* `traceix://skill`
* `traceix://docs/agent-guide`
* `traceix://user/whoami`
* `traceix://hash/{sha256}`
* `traceix://hash/{sha256}/yara`
* `traceix://hash/{sha256}/av`
* `traceix://agent/list`
* `traceix://agent/{agent_uuid}/metadata`
* `traceix://agent/{agent_uuid}/alerts`
* `traceix://job/{uuid}`
* `traceix://av/job/{uuid}`

Use resources for reading existing state.

Use tools for actions such as registration, login, upload, scanning, generation, and polling.

If a resource URI is listed here but not discoverable from the active MCP server, do not assume it exists. Use only resources actually exposed by the connected server.

## MCP Security Rules for Agents

Follow the MCP specification’s trust and safety model.

Before invoking sensitive tools, ensure user intent and consent are clear.

Treat file upload and malware analysis as sensitive operations because they can transmit user data to Traceix and may involve untrusted files.

Do not rely on tool descriptions, annotations, or resource contents as inherently trusted if the server is untrusted. For Traceix, treat the connected Traceix MCP server as the trusted source for Traceix tool schemas and Traceix resources, but still validate inputs before calling tools.

For upload operations:

* show or preserve the filename being uploaded
* ensure the file is within the user-approved scope
* do not upload unrelated files
* do not upload hidden or sensitive files unless explicitly approved
* do not expose credentials in final output
* do not claim a file is safe solely because no results were found

## File Safety Rules

Only upload files the user explicitly selected, attached, provided, or approved.

Do not upload:

* credential files
* API keys
* SSH keys
* wallet keys
* browser profiles
* password stores
* unrelated private documents
* system files
* hidden configuration files
* files outside the user’s stated scope

If the file identity is ambiguous, ask which file the user wants analyzed.

If the file seems sensitive, ask for confirmation before upload.

If the user asks for broad analysis of an approved file and base64 content is available, proceed with `traceix_full_file_upload`.

## Error Handling

If a Traceix tool returns an error, summarize the error plainly and provide the next concrete step.

Common cases:

### Invalid Token

Ask the user to log in again with `traceix_user_login`.

### Invalid API Key

Use `traceix_user_get_api_key` after login, then retry the analysis tool.

### Invalid SHA-256

Ask the user for a valid 64-character hexadecimal SHA-256 hash.

### Missing Filename

Ask for the original filename.

### Missing Base64 Content

Ask for the base64-encoded file content or for the user to provide the file through a workflow that can supply base64 content.

### File Path Provided

Do not call the upload tool with `file_path`. Tell the user the current Traceix MCP server accepts only `filename` and `file_base64`.

### Invalid Base64

Tell the user the base64 file content could not be decoded and ask them to retry the upload.

### File Too Large

Tell the user the file exceeds the maximum upload size and cannot be uploaded through the current Traceix MCP server.

The current server limit is 180 MiB.

### Job Pending

Report the UUID and current status. Use the appropriate polling tool.

### No Results Found

Report that Traceix returned no matching result. Do not treat this as proof that the file or hash is safe.

### API Unavailable

Report that the Traceix API could not be reached and suggest retrying the operation.

### MCP Tool Discovery Fails

Report that the MCP client could not discover Traceix tools. Verify the MCP endpoint, transport, server availability, and client MCP support.

### MCP Resource Read Fails

Report that the requested MCP resource could not be read. Do not substitute stale or guessed resource content unless the user explicitly provided it.

## Output Style

Report results clearly and operationally.

For full analysis, organize the answer into:

1. File hash
2. Classification result
3. YARA result
4. CAPA status/result
5. EXIF status/result
6. AV status/result
7. Pending jobs and polling instructions
8. Errors, if any

If only partial results are available, state which parts completed and which are still pending.

Do not overstate confidence. Use the actual Traceix outputs.

For security-sensitive results, separate observed facts from interpretation.

Use language such as:

* "Traceix returned..."
* "The job is still pending..."
* "No matching result was returned..."
* "This does not prove the file is safe..."

Do not say:

* "This file is definitely safe"
* "This hash is clean"
* "Traceix proves this is malware"
* "The job completed" unless a completion status was returned

## Tool Reference

### `traceix_register_user`

Register a new Traceix user.

Use when the user needs a new Traceix account.

Required input:

* `email_address`
* `password`

### `traceix_user_login`

Log in to Traceix.

Use when the user needs a token.

Required input:

* `email_address`
* `password`

### `traceix_user_get_api_key`

Retrieve or generate a Traceix API key.

Use after login.

Required input:

* `token`

### `traceix_user_whoami`

Inspect the current Traceix user account.

Required input:

* `token`

### `traceix_search_sha_hash`

Search Traceix by SHA-256 hash.

Required input:

* `sha256`
* `api_key`

### `traceix_upload_and_classify`

Upload and classify a base64-encoded file.

Use only when the user asks specifically for classification only.

Required input:

* `filename`
* `file_base64`
* `api_key`

### `traceix_get_file_hash`

Upload a base64-encoded file and return its hash.

Use only when the user asks specifically for the hash only.

Required input:

* `filename`
* `file_base64`
* `api_key`

### `traceix_generate_yara_rule`

Generate a YARA rule from a base64-encoded file.

Use only when the user asks specifically for YARA generation only.

Required input:

* `filename`
* `file_base64`
* `api_key`

### `traceix_get_yara_rule_by_hash`

Retrieve a YARA rule by SHA-256 hash.

Required input:

* `sha256`
* `api_key`

### `traceix_start_capa_extraction`

Start CAPA extraction from a base64-encoded file.

Use only when the user asks specifically for CAPA only.

Required input:

* `filename`
* `file_base64`
* `api_key`

Returns a job UUID when accepted.

### `traceix_start_exif_extraction`

Start EXIF extraction from a base64-encoded file.

Use only when the user asks specifically for EXIF only.

Required input:

* `filename`
* `file_base64`
* `api_key`

Returns a job UUID when accepted.

### `traceix_check_job_status`

Poll CAPA, EXIF, or shared Traceix async job status.

Required input:

* `uuid`
* `api_key`

### `traceix_start_av_scan`

Start AV scanning from a base64-encoded file.

Use only when the user asks specifically for AV only.

Required input:

* `filename`
* `file_base64`
* `api_key`

Returns a job UUID when accepted.

### `traceix_get_av_scan_status`

Poll AV scan status.

Required input:

* `uuid`
* `api_key`

### `traceix_get_av_scan_by_hash`

Retrieve AV results by SHA-256 hash.

Required input:

* `sha256`
* `api_key`

### `traceix_full_file_upload`

Run the default full Traceix analysis workflow on a base64-encoded file.

Use this for broad file-analysis requests.

Required input:

* `filename`
* `file_base64`
* `api_key`

Starts:

* hash calculation
* classification
* YARA generation
* CAPA extraction
* EXIF extraction
* AV scan

Returns immediate results and async job UUIDs.

### `traceix_full_file_upload_status`

Poll async jobs returned by `traceix_full_file_upload`.

Required input:

* `api_key`

Plus at least one of:

* `capa_uuid`
* `exif_uuid`
* `av_uuid`

Use this after `traceix_full_file_upload` when async jobs are pending.

## Decision Rules

Use these rules in order:

1. If the user asks a protocol-level MCP question, consult the official MCP documentation references above.
2. If the user asks a Traceix workflow question, follow this guide.
3. If the user gives a file and asks for broad analysis, use `traceix_full_file_upload` only when `filename` and `file_base64` are available.
4. If the user gives a file and asks an ambiguous analysis question, use `traceix_full_file_upload` only when `filename` and `file_base64` are available.
5. If the user gives a file and asks for one specific artifact, use the matching narrow tool only when `filename` and `file_base64` are available.
6. If the user gives a SHA-256 hash and asks for broad investigation, use the hash investigation workflow.
7. If the user gives a SHA-256 hash and asks for one specific artifact, use the matching hash lookup tool.
8. If credentials are missing, help the user log in and retrieve an API key.
9. If base64 file content is missing, do not call upload tools.
10. If a job UUID is returned, poll with the correct status tool.
11. If a result is pending, say it is pending and preserve the UUID.
12. If an error occurs, report the error and next step.
13. Do not upload files without user approval.

## Example Agent Flows

### Broad File Request

User: "Analyze this file."

Action:

1. Confirm the file is approved for upload.
2. Obtain or use the provided `filename` and `file_base64`.
3. Call `traceix_full_file_upload` with `filename`, `file_base64`, and `api_key`.
4. Report immediate results.
5. Poll pending jobs with `traceix_full_file_upload_status` if UUIDs were returned.

### Narrow File Request

User: "Just generate a YARA rule for this file."

Action:

1. Obtain or use the provided `filename` and `file_base64`.
2. Call `traceix_generate_yara_rule` with `filename`, `file_base64`, and `api_key`.
3. Return the YARA result.
4. Do not run full upload.

### Hash Request

User: "Check this SHA-256."

Action:

1. Validate the SHA-256.
2. Call `traceix_search_sha_hash`.
3. If broad investigation is implied, also call `traceix_get_yara_rule_by_hash` and `traceix_get_av_scan_by_hash`.

### AV-Only Request

User: "Run AV on this file."

Action:

1. Obtain or use the provided `filename` and `file_base64`.
2. Call `traceix_start_av_scan` with `filename`, `file_base64`, and `api_key`.
3. Return the UUID.
4. Poll with `traceix_get_av_scan_status`.

### CAPA-Only Request

User: "Run CAPA on this file."

Action:

1. Obtain or use the provided `filename` and `file_base64`.
2. Call `traceix_start_capa_extraction` with `filename`, `file_base64`, and `api_key`.
3. Return the UUID.
4. Poll with `traceix_check_job_status`.

### Pending Job Request

User: "Check this job UUID."

Action:

1. Determine whether it is a general Traceix job or AV job from context.
2. Use `traceix_check_job_status` for CAPA, EXIF, or general jobs.
3. Use `traceix_get_av_scan_status` for AV jobs.
4. If context is missing, ask which job type it is.

### MCP Resource Request

User: "Read the Traceix agent guide."

Action:

1. Read `traceix://docs/agent-guide` if the MCP server exposes it.
2. Treat the resource as read-only context.
3. Do not call upload, scan, login, or mutation tools unless the user asks for an action.

### MCP Tool Discovery Request

User: "What Traceix tools are available?"

Action:

1. Use MCP tool discovery from the connected client.
2. Report the discovered tools and their input schemas.
3. Do not infer tools that are not exposed by the active server.

## Compatibility Notes

Older versions of this guide used the tool names:

* `traceix_full_upload`
* `traceix_full_upload_status`

The current MCP server uses:

* `traceix_full_file_upload`
* `traceix_full_file_upload_status`

Use the current names.

Older versions of this guide allowed either `file_path` or `filename` plus `file_base64`.

The current MCP server accepts only:

* `filename`
* `file_base64`
* `api_key`

Do not use `file_path`.

## Final Reminder

Default to `traceix_full_file_upload` for file-based analysis unless the user explicitly asks for a narrower result.

For upload-capable tools, provide exactly the approved file’s `filename`, its `file_base64` content, and the Traceix `api_key`.

Use official MCP documentation for protocol-level questions.

Use Traceix MCP resources for read-only context.

Use Traceix MCP tools for actions.

Do not pass `file_path`.

Do not upload unapproved files.

Do not fabricate results.

Report pending async work as pending with UUIDs and polling instructions.