API Reference — Forage Docs

Overview

The Forage MCP server exposes a set of tools your AI agent can call to query the knowledge graph. When you connect via MCP, these tools are automatically advertised to the agent — you don't need to configure them manually.

Base URL: http://localhost:9989/mcp

All tools follow the MCP specification. Parameters are passed as JSON and results are returned as structured text.

`search_symbols`

Search for symbols (functions, classes, variables, types) across the entire codebase.

Parameter	Type	Required	Description
`query`	string	Yes	Name or partial name to search for
`type`	string	No	Filter by symbol type: `function`, `class`, `variable`, `type`, `interface`
`file`	string	No	Limit results to a specific file or directory path
`limit`	number	No	Maximum results to return (default: 20)

Example

{
  "query": "authenticate",
  "type": "function",
  "limit": 10
}

`get_symbol`

Get the full source, docstring, location, and call graph for a specific symbol.

Parameter	Type	Required	Description
`name`	string	Yes	Exact symbol name
`file`	string	No	File path (required if the symbol name is ambiguous)

`get_file`

Retrieve the contents of a file along with its indexed metadata (symbols, imports, language).

Parameter	Type	Required	Description
`path`	string	Yes	Path relative to the project root
`lines`	string	No	Line range to return, e.g. `"40-80"`

`get_dependencies`

List all files and modules that a given file imports or depends on.

Parameter	Type	Required	Description
`path`	string	Yes	File path relative to project root
`depth`	number	No	How many levels of transitive dependencies to traverse (default: 1)

`get_dependents`

List all files that import or depend on the given file. Useful for impact analysis before making changes.

Parameter	Type	Required	Description
`path`	string	Yes	File path relative to project root
`depth`	number	No	Transitive depth (default: 1)

`search_annotations`

Search indexed code annotations (TODO, FIXME, BUG, HACK, DEPRECATED, NOTE) across the entire codebase.

Parameter	Type	Required	Description
`type`	string	No	Filter by annotation type. Omit to return all types.
`query`	string	No	Full-text search within annotation text
`file`	string	No	Limit to a file or directory
`limit`	number	No	Max results (default: 50)

`get_graph_summary`

Return high-level statistics about the current knowledge graph: file count, symbol count, language breakdown, last indexed time, and graph health.

No parameters required.

`natural_language_query`

Ask a free-form question about the codebase. Forage translates it into graph queries and returns a structured answer.

Parameter	Type	Required	Description
`question`	string	Yes	Your question in plain English

Example

{
  "question": "Which functions call the database connection pool, and which files define them?"
}