Agent Integration Guide

DocSentinel supports complementary interoperability protocols:

• MCP exposes narrow tools to coding agents and workflow platforms.
• A2A 1.0 exposes DocSentinel as a remote security-assessment agent.

Both protocols use the same assessment task service as the REST API and React console. Agent submissions always require human review.

Security Model | 安全模型

• Document paths must resolve inside MCP_DOCUMENT_ROOTS.
• With an empty AGENT_GATEWAY_TOKEN, remote protocol endpoints accept loopback clients only.
• Network exposure requires a bearer token, TLS, and preferably an upstream OIDC-aware proxy.
• Protocol adapters do not return raw source documents. Assessment content may still be sent to the configured LLM provider, so local/private LLM policy remains important.
• Agents can submit and inspect assessments, but cannot approve their own work.

MCP

Tools

Tool	Purpose
submit_document_assessment	Submit a document asynchronously; returns the shared assessment task ID.
get_assessment_status	Read task status and the available draft report.
query_knowledge_base	Retrieve approved KB chunks, limited to 10 results.
get_agent_gateway_status	Inspect enabled protocols and access mode.
assess_document	Compatibility tool that waits for a draft assessment.

Local stdio

Use stdio for Claude Desktop, Cursor, and other agents running on the same machine:

{
  "mcpServers": {
    "docsentinel": {
      "command": "/path/to/DocSentinel/.venv/bin/python",
      "args": ["/path/to/DocSentinel/app/mcp_server.py"],
      "env": {
        "MCP_DOCUMENT_ROOTS": "/absolute/path/to/approved/documents",
        "LLM_PROVIDER": "ollama"
      }
    }
  }
}

Use : to separate multiple roots on macOS/Linux, or ; on Windows.

Streamable HTTP

When FastAPI is running, the MCP endpoint is:

http://localhost:8000/mcp/

For access from another host:

AGENT_GATEWAY_TOKEN=generate-a-long-random-value
AGENT_GATEWAY_PUBLIC_URL=https://docsentinel.internal.example
AGENT_GATEWAY_ALLOWED_HOSTS=docsentinel.internal.example
AGENT_GATEWAY_ALLOWED_ORIGINS=https://trusted-agent-console.internal.example

Clients must send:

Authorization: Bearer <AGENT_GATEWAY_TOKEN>

Use the MCP Inspector or a conforming client to initialize the connection and discover tools. The endpoint is not a conventional REST API. Keep the Host and Origin allow-lists narrow: they are part of MCP's DNS-rebinding protection and must match the deployment URL used by clients.

Docker bridge traffic is not loopback traffic from the container's perspective. Set AGENT_GATEWAY_TOKEN when connecting to MCP or A2A through a published container port.

A2A 1.0

Agent discovery:

http://localhost:8000/.well-known/agent-card.json

JSON-RPC endpoint:

http://localhost:8000/a2a

The Agent Card advertises three skills:

• assess_security_document
• get_security_assessment
• query_security_knowledge

A2A message text must contain a JSON object.

Submit an approved server-side document:

{
  "operation": "assess_document",
  "file_path": "./examples/security-design.md",
  "phase": "design",
  "scenario_id": "architecture-review",
  "skill_id": "ssdlc-design"
}

Retrieve the shared task:

{
  "operation": "get_assessment",
  "task_id": "assessment-task-id"
}

Query security knowledge:

{
  "operation": "query_knowledge_base",
  "query": "PCI DSS privileged access requirements",
  "top_k": 3
}

This first A2A slice references documents already present in an approved server-side root. Cross-host uploads will use opaque document handles in a future phase rather than granting agents broader filesystem access.

Operations

The React console exposes protocol state at:

http://localhost:8000/console/integrations

The machine-readable status endpoint is:

GET /api/v1/integrations/agents/status

Use logs and assessment activity records to trace which entry point created a task (rest, mcp, or a2a).