Bring Your Own Database for Security Graph

Run Security Graph MCP on your infrastructure with PostgreSQL, scoped agent credentials, and your own assessment tools.

Run the Security Graph service against your own PostgreSQL database to keep findings, reports, comments, and review history on your infrastructure. Your agents connect to your MCP endpoint and perform assessments using your chosen models.

This guide is for operating an independent service. For Superagent-managed storage and scans, connect to the hosted Superagent MCP with your organization API key.

PostgreSQL 17 or later is the supported reference backend. You do not need Neo4j. Other databases require implementing and validating the storage adapter contract; they are not selectable backends in the shipped executable.

1. Build the service

With Docker installed and repository access:

git clone https://github.com/superagent-ai/security-graph.git
cd security-graph
docker build -t security-graph:local .

For a local trial that also provisions PostgreSQL, use the repository's Docker Compose quickstart. The steps below use an existing database reachable from the service container.

2. Configure your database

Provision a dedicated PostgreSQL database and store the connection settings in a local, gitignored .env.security-graph file, or inject them through your deployment's secret manager:

DATABASE_URL=postgres://graph_user:URL_ENCODED_PASSWORD@db.example.com:5432/security_graph?sslmode=verify-full
STORAGE_BACKEND=postgres

Replace the example host and credentials. Percent-encode special characters in the password. Use certificate verification for remote connections and mount your provider's CA certificate if required. Keep database credentials on the service; MCP clients receive separate graph credentials.

Apply the service's standalone migrations:

docker run --rm --env-file .env.security-graph \
  security-graph:local migrate

Run migrations before serving the first request and when upgrading. Use a migration role for DDL and a runtime role with the required data privileges in production. Configure database backups and recovery for your deployment.

Keep STORAGE_BACKEND=postgres for this standalone setup.

3. Start the MCP service

docker run -d --name security-graph \
  --env-file .env.security-graph \
  -p 127.0.0.1:8080:8080 \
  security-graph:local serve

The local endpoint is http://127.0.0.1:8080/mcp. For remote agents, put it behind an HTTPS reverse proxy and publish both /mcp and /catalog. The catalog contains public definitions; the MCP endpoint requires authentication. The container listens on port 8080; a host-run binary uses LISTEN_ADDR to configure its listener.

4. Issue a scoped agent key

Create an assessment credential for one organization, agent identity, and asset:

docker run --rm --env-file .env.security-graph \
  security-graph:local issue-key \
  --org acme --actor pr-reviewer \
  --assets acme/payments \
  --scopes read,submit,graph:write \
  --ttl 24h

The sg_ key is printed once; only its hash is stored. Save it in your client's secret storage. Organization and asset access come from the credential, not from tool arguments.

Scope	Allows
`read`	Read authorized records and discover classification choices
`submit`	Submit assessment results and write finding comments
`graph:write`	Create assets and relationships and save classifications; classification writes also require `read`
`disposition`	Change finding triage and report review state
`export`	Read the change feed

Grant disposition explicitly to an agent that should resolve findings. Use --all-assets instead of --assets only when the agent needs organization-wide access. Standalone keys do not authenticate to the hosted Superagent MCP endpoint.

5. Connect and verify your agent

For a client supporting URL and header configuration:

{
  "mcpServers": {
    "security-graph": {
      "url": "https://security-graph.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SECURITY_GRAPH_API_KEY}"
      }
    }
  }
}

Replace the URL with your HTTPS endpoint. Use your client's documented secret mechanism; interpolation varies. A client running on the same machine can use the local HTTP endpoint above.

Ask the agent to register acme/payments, retrieve its context, create an assessment, and save a structured test finding. It should discover current choices through get_classification_options with a query or limit, select both vulnerability types and compliance entries, and save them with the returned catalog version. Read the finding and its connections back through MCP, then finish the report. Follow the shared workflow and the live tool schemas for required inputs.

Local subprocess clients can alternatively launch security-graph stdio with database access and no HTTP key. The trusted launch configuration determines their organization, actor, assets, and permissions. See the stdio guide.

Operate and upgrade

Revoke every credential for an agent when access is no longer needed:

docker run --rm --env-file .env.security-graph \
  security-graph:local revoke-key --org acme --actor pr-reviewer

Upgrade the service and apply its migrations together. Catalog releases ship with the service; agents discover the new choices through MCP and continue reading historical selections using their saved version. No classification model or background inference worker is required.

This deployment supplies security memory. It does not provision Superagent scanners, import another vendor's findings automatically, or connect your database to the hosted Superagent dashboard. Your agent or adapter must investigate external results and submit the required evidence. The change feed is not a complete database replication protocol.