MCP and Agent Skill

SAG exposes read-only knowledge tools to Codex, Claude Code, and other compatible hosts through MCP. A connection can cover the complete knowledge base or use source_id to restrict access to one source.

Get a connection configuration

In SAG, open Settings -> Integrations -> Knowledge Base MCP, select HTTP or a local command, and copy the complete configuration.

Streamable HTTP is recommended:

URL: http://<host>/mcp/?source_id=<SOURCE_ID>
Header: Authorization: Bearer <SAG_TOKEN>

Without source_id, the connection can access every source owned by the current identity. A local source checkout also supports stdio:

SAG_MCP_SOURCE_ID=<SOURCE_ID> python -m sag_api.mcp.server

Install the official Agent Skill

The repository's skills/sag/ directory teaches an Agent to use the intended read-only exploration funnel. Copy it into the corresponding skill directory:

# Claude Code
cp -R skills/sag ~/.claude/skills/sag-knowledge

# Codex
cp -R skills/sag ~/.codex/skills/sag-knowledge

The Skill provides usage guidance; it is not the connection itself. The host still needs the MCP server URL or command and its authentication settings.

Eight read-only tools

Order	Tool	Purpose
1	`list_sources()`	Confirm accessible scope, document counts, and chunk counts
2	`list_documents(source_id?)`	Inspect documents, status, and chunk counts
3	`outline(document_id)`	Browse document structure by heading and rank
4	`search(query, top_k?, source_id?)`	Semantically retrieve numbered evidence with natural language
5	`grep(pattern, limit?, source_id?)`	Locate identifiers, function names, and exact terms
6	`get_chunk(chunk_id, source_id?)`	Read the complete source text for one evidence chunk
7	`read(document_id, offset?, limit?)`	Read an original file in line-based pages
8	`get_entity(name, source_id?)`	Inspect event context related to an entity

Every tool returns MCP text content. An empty result returns an explanatory placeholder instead of raising "no data" as a tool failure.

Recommended exploration funnel

list_sources
  -> list_documents
  -> outline
  -> search or grep
  -> get_chunk or paged read

This order establishes scope, reveals structure, and reads only the source text that is necessary. It consumes less context than starting with a full-document read and makes verifiable citations easier to produce.

Choose search or grep

Use search for questions, concepts, and approximate expressions, such as "What is the reimbursement approval chain?"
Use grep for known strings such as INV-2024, a function name, or a standard number.
When asked for provenance, pass the result's chunk_id to get_chunk.
Page through large files from offset=1, with no more than 500 lines per limit.

Authentication and scope

An HTTP configuration normally contains the current SAG JWT. It grants read access to the corresponding knowledge scope. Never commit it to a public repository or include it in an issue or log.

For least privilege, give each Agent a URL that includes source_id. SAG MCP is currently a knowledge-reading surface and does not expose delete, upload, or modification tools.