Skip to main content
Glama
nh4ttruong

secobserve-mcp

by nh4ttruong
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Pull Findings From Configured API

secobserve_api_import

Pull vulnerability findings from a configured upstream API into SecObserve, assigning them to a branch and service.

Instructions

Pull findings into SecObserve from an upstream API it already has credentials for.

The credentials, base URL and parser come from an API configuration stored on the product; list them with secobserve_list(resource="api_configurations"). SecObserve fetches and parses inside the request, so the call blocks and can outlast the HTTP timeout. When it does, this returns the state of the work rather than a bare timeout, because the import is still running server-side.

Args: api_configuration_id (Optional[int]) or api_configuration_name (Optional[str]): exactly one. branch_id (Optional[int]) with the id form, or branch_name (Optional[str]) with the name form; a named branch is created if missing. service (Optional[str]): Service to attach findings to. docker_image_name_tag / endpoint_url (Optional[str]): origin metadata.

Returns: str: observations_new, observations_updated and observations_resolved as reported by the API, one per line. On a timeout, a "Still running" text instead: no counts, the secobserve_list call on vulnerability_checks that shows the import landing, and that row's last_import from before the call, which a later value beats.

Examples: - Use when: "refresh findings from our Dependency Track project" -> api_configuration_name="dtrack-portal", branch_name="main" - Use when: scripted re-import after an upstream scan -> api_configuration_id=5 - Don't use when: you have the report file locally (use secobserve_upload_file).

Error Handling: 400 means the upstream call or parse failed -- the message carries the upstream error. A timeout is answered with "Still running" and the query that settles it; never retry on one, since the first import is still going and a second call would run the whole fetch again.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
serviceNoService name to attach the findings to.
branch_idNoTarget branch by id, with the id form.
branch_nameNoTarget branch by name, with the name form; created if missing.
endpoint_urlNoOrigin metadata: URL.
api_configuration_idNoId of the API configuration to pull from. Give this or api_configuration_name.
docker_image_name_tagNoOrigin metadata: image.
api_configuration_nameNoName of the API configuration to pull from.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv0.3.0
    • removedInput schema / $defs
      Removed value: -{
-  "ApiImportInput": {
-    "additionalProperties": false,
-    "description": "Input model for pulling findings from a configured upstream API.",
-    "properties": {
-      "api_configuration_id": {
-        "anyOf": [
-          {
-            "minimum": 1,
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Id of the API configuration to pull from. Give this or api_configuration_name.",
-        "title": "Api Configuration Id"
-      },
-      "api_configuration_name": {
-        "anyOf": [
-          {
-            "maxLength": 255,
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Name of the API configuration to pull from.",
-        "title": "Api Configuration Name"
-      },
-      "branch_id": {
-        "anyOf": [
-          {
-            "minimum": 1,
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Target branch by id, with the id form.",
-        "title": "Branch Id"
-      },
-      "branch_name": {
-        "anyOf": [
-          {
-            "maxLength": 255,
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Target branch by name, with the name form; created if missing.",
-        "title": "Branch Name"
-      },
-      "docker_image_name_tag": {
-        "anyOf": [
-          {
-            "maxLength": 513,
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Origin metadata: image.",
-        "title": "Docker Image Name Tag"
-      },
-      "endpoint_url": {
-        "anyOf": [
-          {
-            "maxLength": 2048,
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Origin metadata: URL.",
-        "title": "Endpoint Url"
-      },
-      "service": {
-        "anyOf": [
-          {
-            "maxLength": 255,
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Service name to attach the findings to.",
-        "title": "Service"
-      }
-    },
-    "title": "ApiImportInput",
-    "type": "object"
-  }
-}
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / api_configuration_id
      Added value: +{
+  "anyOf": [
+    {
+      "minimum": 1,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Id of the API configuration to pull from. Give this or api_configuration_name.",
+  "title": "Api Configuration Id"
+}
    • addedInput schema / properties / api_configuration_name
      Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 255,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Name of the API configuration to pull from.",
+  "title": "Api Configuration Name"
+}
    • addedInput schema / properties / branch_id
      Added value: +{
+  "anyOf": [
+    {
+      "minimum": 1,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Target branch by id, with the id form.",
+  "title": "Branch Id"
+}
    • addedInput schema / properties / branch_name
      Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 255,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Target branch by name, with the name form; created if missing.",
+  "title": "Branch Name"
+}
    • addedInput schema / properties / docker_image_name_tag
      Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 513,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Origin metadata: image.",
+  "title": "Docker Image Name Tag"
+}
    • addedInput schema / properties / endpoint_url
      Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 2048,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Origin metadata: URL.",
+  "title": "Endpoint Url"
+}
    • removedInput schema / properties / params
      Removed value: -{
-  "$ref": "#/$defs/ApiImportInput"
-}
    • addedInput schema / properties / service
      Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 255,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Service name to attach the findings to.",
+  "title": "Service"
+}
    • removedInput schema / required
      Removed value: -[
-  "params"
-]
  2. First observedv0.1.2

TDQS

A5/5.0
Behavior5/5

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

The description discloses important runtime behavior beyond the annotations: the call blocks and can outlast the HTTP timeout, the import continues server-side, a timeout returns "Still running" rather than a bare error, and a second call would run the fetch again. It also explains the meaning of a 400 error. This adds substantial transparency that annotations alone do not provide.

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

Conciseness5/5

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

The description is long but every section earns its place: core action, prerequisite discovery, parameter constraints, return-value format, examples, and error handling. The most important scoping sentence is front-loaded, and the structured Args/Returns/Error Handling sections make the content scannable. There is no fluff or repetition.

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 7-parameter tool with no required params, timeout behavior, and side effects like branch creation, the description is remarkably complete. It covers prerequisites, selection constraints, return semantics, failure modes, retry implications, and alternatives. The presence of an output schema means the return description is a bonus, not a necessity, further raising completeness.

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?

Although the schema already covers all 7 parameters at 100%, the description adds relational semantics: exactly one of api_configuration_id or api_configuration_name must be given; branch_id corresponds to the id form while branch_name creates the branch if missing; and docker_image_name_tag/endpoint_url are grouped as origin metadata. This gives agents actionable rules for choosing and combining parameters that the schema fields do not express.

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 description opens with a specific verb and resource: "Pull findings into SecObserve from an upstream API it already has credentials for." This clearly distinguishes it from the sibling upload_file tool, and the explicit "Don't use when" example reinforces the boundary. The title also aligns with the described action.

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 gives concrete when-to-use examples ("refresh findings from our Dependency Track project", "scripted re-import after an upstream scan") and an explicit when-not-to-use case with a named alternative (secobserve_upload_file). It also provides critical operational guidance: never retry on timeout, and use secobserve_list to verify the import.

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

Deploy Server

Other Tools