secobserve-mcp

Import File Into SecObserve

secobserve_upload_file

Import a local scan report, SBOM, or VEX file into SecObserve to deduplicate findings, apply rules, and resolve removed issues. Supports product, branch, service, and origin metadata.

Instructions

Import a local scanner report, SBOM or VEX document into SecObserve.

This is the correct way to get findings in: the import deduplicates against existing observations, applies rules, resolves findings that disappeared from the report, and records a vulnerability check. Creating observations by hand with secobserve_create does none of that.

The file must live under the server's import directory (SECOBSERVE_IMPORT_DIR, the working directory by default) and be at most 64 MiB.

Args: params (UploadInput): Validated input containing: - kind (str): "observations", "sbom" or "vex". - file_path (str): Path to the report, absolute or relative to the import directory. - product_id (Optional[int]) / product_name (Optional[str]): exactly one, ignored for kind="vex" which matches on the document's own product data. - branch_id (Optional[int]) with product_id, or branch_name (Optional[str]) with product_name; a named branch is created if missing. - service (Optional[str]): Service to attach findings to. - suppress_licenses (Optional[bool]): kind="observations" only. - docker_image_name_tag / endpoint_url / kubernetes_cluster / kubernetes_namespace (Optional[str]): origin metadata recorded on each finding.

Returns: str: The import counts as reported by the API, one per line -- for "observations": observations_new, observations_updated, observations_resolved plus license_components_new/updated/deleted; for "sbom": the license_components_* counts; for "vex": the API's summary.

Examples: - Use when: "import trivy-results.json into product 12, branch main" -> kind="observations", file_path="trivy-results.json", product_id=12, branch_id=3 - Use when: "load this SBOM for the release branch" -> kind="sbom", file_path="sbom.cdx.json", product_name="Portal", branch_name="release-2.1" - Use when: "apply the vendor's VEX" -> kind="vex", file_path="vendor.openvex.json" - Don't use when: the data is behind an API you have configured in SecObserve (use secobserve_api_import).

Error Handling: A path outside the import directory, a missing, empty or oversized file is refused before any request is made. 400 usually means the parser could not read the format -- check the product's expected parser with secobserve_list(resource="parsers"). Read-only mode blocks the call.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`params`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.2Sep 17, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses significant behavioral details: deduplication against existing observations, rule application, resolution of disappeared findings, vulnerability check recording, the 64 MiB size limit, the import-directory requirement, and read-only mode blocking the call. It also explains likely 400 errors and how to diagnose parser mismatches.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is lengthy but well-organized with clear sections (Args, Returns, Examples, Error Handling) and front-loads the core purpose and key behavior in the first paragraphs. Some parameter-level detail repeats schema information, but the relational and conditional guidance justifies the length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex upload tool with many optional parameters, the description covers file prerequisites, parameter pairing constraints, per-kind return counts, common failure modes, and sibling routing. Combined with the output schema and annotations, an agent has everything needed to invoke it correctly in normal and edge cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though the schema contains per-field descriptions, the description adds critical cross-parameter semantics missing from the schema: product_id and product_name are mutually exclusive, branch_name is created if missing, branch_id pairs with product_id, suppress_licenses applies only to kind='observations', and VEX imports ignore product targeting. This compensates fully for any schema coverage gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence uses a specific verb and resource: 'Import a local scanner report, SBOM or VEX document into SecObserve.' It clearly distinguishes itself from sibling tools by naming secobserve_create and secobserve_api_import as the alternatives for different scenarios, so an agent can select it correctly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says this is 'the correct way to get findings in' and explains why hand-created observations via secobserve_create are not equivalent. It also provides a concrete exclusion: 'Don't use when the data is behind an API... (use secobserve_api_import)', plus realistic examples that map natural-language requests to parameter values.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server