Which integrations are available for this server?

Uses OpenAI embeddings (text-embedding-3-small) for the research pipeline.

How do I use synapse-research?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@synapse-research Research the latest trends in AI alignment for 2025" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

synapse-research

by NimbleBrainInc

Overview Schema Related Servers Score Discussions

Python

Hybrid

synapse-research

mpak NimbleBrain Discord License: MIT

Deep-research MCP app. Exposes one task-augmented tool (start_research) that runs GPT-Researcher against Tavily (web search), Anthropic Claude (planner + writer LLM), and OpenAI (embeddings only), and streams progress back through both the MCP tasks protocol and the Upjack entity stream. Fully compliant with the MCP 2025-11-25 draft tasks utility via FastMCP 3.

View on mpak registry | Built by NimbleBrain

Quick Start

Install via mpak into your NimbleBrain workspace:

mpak install @nimblebraininc/synapse-research

Set the three required credentials in your host's shell (Bun auto-loads .env, or export directly):

export ANTHROPIC_API_KEY=sk-ant-...
export TAVILY_API_KEY=tvly-...
export OPENAI_API_KEY=sk-...

Run a research task from your agent chat:

"Research what's new with Model Context Protocol in 2026"

The agent fires start_research, the worker streams progress into the chat UI and into the Synapse sidebar dashboard, and you get back a markdown report in ~30s–3min.

Related MCP server: gpt-researcher-mcp

Architecture

chat: "research X"
  │
  ▼
NimbleBrain engine ──┐
                     │  tools/call (task-augmented)
                     ▼
            FastMCP server (this app)
                     │
                     ├─► creates research_run entity (status=working)
                     ├─► spawns worker (asyncio)
                     │     │
                     │     ├─► ctx.report_progress  ──► notifications/tasks/status ──► engine
                     │     └─► app.update_entity    ──► filesystem ──► Synapse UI live stream
                     │
                     └─► returns CreateTaskResult immediately
                         (engine polls tasks/get, retrieves via tasks/result when terminal)

Two independent channels update in lockstep:

Engine channel — MCP task status notifications. The engine uses these to render progress in the chat UI and to stabilise polling cadence.
UI channel — entity writes via Upjack. The Synapse sidebar app reads the entity stream to render a live dashboard of runs.

UI retry flow

The sidebar's "Retry with same query" button uses useCallToolAsTask("start_research") from the Synapse SDK (≥ 0.7.0). The task handle returns a taskId in under a second; the new research_run entity materialises shortly after (the worker creates it as its first action), and the UI navigates to the new detail page off the entity channel — not by waiting on the task's terminal result, which arrives minutes later. Second click on the button while "Starting…" routes through handle.cancel().

Legacy hosts (platform builds prior to the tasks-capability advertisement) cause callToolAsTask to throw. The UI catches that case and falls back to synapse.callTool fire-and-forget, so the feature keeps working with older deploys — only the starting-state indicator and the cancel handle degrade.

Configuration

Credentials (declared as `user_config` in `manifest.json`)

The host runtime prompts for these at install time or resolves them from a workspace-scoped store, then injects them into the bundle subprocess via mcp_config.env:

Config key	Env var exposed	Purpose
`anthropic_api_key`	`ANTHROPIC_API_KEY`	Claude LLM — planning + report writing
`tavily_api_key`	`TAVILY_API_KEY`	Web search
`openai_api_key`	`OPENAI_API_KEY`	Embeddings only (`text-embedding-3-small`)

All three are required and marked sensitive: true.

Routing (hard-coded in `mcp_config.env`)

Not tenant-tunable in v1 — set directly in the manifest:

RETRIEVER=tavily
FAST_LLM=anthropic:claude-haiku-4-5
SMART_LLM=anthropic:claude-sonnet-4-6
STRATEGIC_LLM=anthropic:claude-sonnet-4-6
EMBEDDING=openai:text-embedding-3-small

To change an LLM or retriever, edit manifest.json and reinstall the bundle. Promoting any of these to user_config is a one-line change if per-workspace tuning is needed.

Cost and latency

Typical run: 30s–3min.
Typical cost: $0.15–$0.60/run on Sonnet 4.6 + Tavily advanced + OpenAI embeddings.
Hard-cap: 5 minutes via asyncio.wait_for. Longer runs are marked failed with a timeout error.

Data layout

One entity: research_run. Lives under:

$UPJACK_ROOT/apps/research/data/research_runs/{id}.json

Data-root resolution priority:

UPJACK_ROOT env var
MPAK_WORKSPACE env var
~/.synapse-research (fallback)

Each workspace spawns its own server process with its own root. There is no cross-workspace state inside the server.

Running locally

Install deps

uv sync
cd ui && npm install && npm run build && cd ..

Stdio (Claude Desktop, any MCP client)

uv run python -m mcp_research.server

HTTP (NimbleBrain platform)

uv run uvicorn mcp_research.server:app --port 8002

Tests (keyless — no API keys required)

uv run pytest tests/ -v

The spec-compliance suite (tests/test_spec_compliance.py) exercises every MUST from the MCP tasks draft: capability advertisement, execution.taskSupport gating, tasks/get|result|cancel|list, TTL behaviour, progress notifications, workspace isolation. The worker suite (tests/test_worker.py) covers happy path, cancel, failure, monotonic progress, and source streaming. All tests use a FakeGPTR monkeypatch so real providers are never called in CI.

Tool reference

Tool	Task support	Description
`start_research`	`optional`	The only custom tool. Runs the research worker end-to-end.
`get_research_run`	n/a	Auto-generated entity tool (read by id).
`list_research_runs`	n/a	Auto-generated entity tool.
`search_research_runs`	n/a	Auto-generated entity tool.
`delete_research_run`	n/a	Auto-generated entity tool (soft delete).

Cancellation is handled at the MCP protocol level via tasks/cancel. The worker catches asyncio.CancelledError, flips the entity to cancelled, and re-raises so FastMCP transitions the task to its cancelled terminal state.

Contributing

See CLAUDE.md for the architecture walkthrough, commands, conventions, and build pipeline.

Quality gates (run before opening a PR):

uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
uv run ty check src/
uv run pytest tests/ -v
cd ui && npm ci && npm run build

CI enforces the same gates — see .github/workflows/ci.yml.

Ecosystem

NimbleBrain — the agent platform this app runs on
mpak — MCP bundle registry where releases are published
Upjack — declarative AI-app framework (entity schemas, skills, hooks)
Synapse SDK — React hooks powering the UI
GPT-Researcher — Apache-2.0 research engine this app wraps
Discord community

License

MIT — see LICENSE.

Available Tools

7 tools

add_fieldB

Add a new field to an entity schema. Validates the change is safe, writes the updated schema to disk, and reloads it.

ParametersJSON Schema

Name	Required	Description	Default
`default`	Yes
`required`	No
`field_name`	Yes
`field_type`	Yes
`description`	No
`entity_type`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.3/5.0

Behavior3/5

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

No annotations are provided, so the description must carry the full burden. It indicates mutation by mentioning writing to disk and reloading, and validation for safety. However, it omits details on error handling, permissions, or other side effects.

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 two sentences, no redundant information, and immediately states the core function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 6 parameters and no parameter descriptions, the tool is incomplete for an agent to use correctly. The output schema exists but is not shown; the description covers high-level behavior but lacks crucial input semantics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the description does not explain any of the 6 parameters. The agent receives no guidance on the meaning or usage of fields like 'default', 'required', 'field_name', etc.

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 clearly states the action ('Add a new field to an entity schema') and the resource ('entity schema'). The sibling tools are all about research runs, so this tool is distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes what happens (validate, write, reload) but does not provide explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites.

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

delete_research_runA

Delete a research_run by ID. Soft delete by default (sets status to 'deleted'). Set hard=true to permanently remove. IDs start with rr_.

ParametersJSON Schema

Name	Required	Description	Default
`hard`	No	Permanently remove instead of soft delete.
`research_run_id`	Yes	research_run ID (rr_...)

Output Schema

ParametersJSON Schema

Name	Required	Description
`query`	Yes	The research query or topic
`title`	No	Short human label for the run (3–8 words). Distinct from `query`, which holds the full research brief. Auto-generated server-side via the FAST_LLM shortly after the entity is created when not supplied by the caller. Renders in list rows and as the detail-view heading; the UI falls back to a truncated `query` while title is null.
`report`	No	The final markdown report. Populated when status becomes 'completed'.
`sources`	No	Sources consulted during the research run. Populated incrementally during the 'Gathering sources' phase.
`progress`	No	Completion percent (0–100)
`run_status`	No	Execution status, mirrors the MCP task status for the underlying run. Distinct from the base entity `status` field which tracks lifecycle (active/archived/deleted).
`started_at`	No	ISO 8601 timestamp when the run started
`completed_at`	No	ISO 8601 timestamp when the run reached a terminal state
`error_message`	No	Error details when status is 'failed'
`phase_history`	No	Timeline of phase transitions for this run. Append-only; each entry records when a phase started and when it ended (null for the currently-running phase). Preserved after completion so the time distribution is auditable forever.
`status_message`	No	Short human-readable description of the current phase
`last_heartbeat_at`	No	Last time the worker emitted any signal, including liveness heartbeats. Updated continuously while the run is working — independent of progress, which only advances on real phase transitions. Used by the UI to surface staleness when no signal has arrived in 10s+ (separates 'still alive but slow' from 'actually hung').
`current_phase_started_at`	No	ISO 8601 timestamp recording when the currently-active phase began. The UI derives the elapsed-time suffix in the status line from this — `now - current_phase_started_at`, recomputed every second client-side. This decouples display cadence from worker write cadence: the worker only updates this value on phase transitions (a stable input), the UI animates the display (the smooth output). Cleared on terminal transitions.

TDQS

A4.5/5.0

Behavior4/5

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

No annotations are provided, so description carries full burden. It discloses the default soft delete behavior (status set to 'deleted'), the hard permanent delete option, and the ID prefix. It does not mention required permissions, rate limits, or cascading effects, but the core behavioral traits are well covered.

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?

Description is three concise sentences with no redundancy. It front-loads the core purpose and then adds behavioral nuances efficiently.

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?

Given the tool's simplicity (2 params, no nested objects) and presence of an output schema, the description covers all necessary behavioral details: soft vs hard delete, default behavior, and ID format. It is adequately complete for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. Description adds value by clarifying the 'hard' parameter's effect ('to permanently remove') and reiterating the ID prefix. This enriches the parameter meaning beyond schema alone.

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?

Description clearly states 'Delete a research_run by ID', specifying both the action and resource. It also explains soft vs hard delete. Sibling tools are all non-destructive (get, list, search) or other actions (add_field, rebuild, start), so this tool's deletion purpose is distinct and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implicitly indicates when to use (to delete a research_run) and explains default soft delete behavior. It does not explicitly exclude use cases or mention alternatives, but given sibling tools are read or other operations, the context is clear enough.

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

get_research_runB

Get a research_run by ID. IDs start with rr_.

ParametersJSON Schema

Name	Required	Description	Default
`research_run_id`	Yes	research_run ID (rr_...)

Output Schema

ParametersJSON Schema

Name	Required	Description
`query`	Yes	The research query or topic
`title`	No	Short human label for the run (3–8 words). Distinct from `query`, which holds the full research brief. Auto-generated server-side via the FAST_LLM shortly after the entity is created when not supplied by the caller. Renders in list rows and as the detail-view heading; the UI falls back to a truncated `query` while title is null.
`report`	No	The final markdown report. Populated when status becomes 'completed'.
`sources`	No	Sources consulted during the research run. Populated incrementally during the 'Gathering sources' phase.
`progress`	No	Completion percent (0–100)
`run_status`	No	Execution status, mirrors the MCP task status for the underlying run. Distinct from the base entity `status` field which tracks lifecycle (active/archived/deleted).
`started_at`	No	ISO 8601 timestamp when the run started
`completed_at`	No	ISO 8601 timestamp when the run reached a terminal state
`error_message`	No	Error details when status is 'failed'
`phase_history`	No	Timeline of phase transitions for this run. Append-only; each entry records when a phase started and when it ended (null for the currently-running phase). Preserved after completion so the time distribution is auditable forever.
`status_message`	No	Short human-readable description of the current phase
`last_heartbeat_at`	No	Last time the worker emitted any signal, including liveness heartbeats. Updated continuously while the run is working — independent of progress, which only advances on real phase transitions. Used by the UI to surface staleness when no signal has arrived in 10s+ (separates 'still alive but slow' from 'actually hung').
`current_phase_started_at`	No	ISO 8601 timestamp recording when the currently-active phase began. The UI derives the elapsed-time suffix in the status line from this — `now - current_phase_started_at`, recomputed every second client-side. This decouples display cadence from worker write cadence: the worker only updates this value on phase transitions (a stable input), the UI animates the display (the smooth output). Cleared on terminal transitions.

TDQS

B3.1/5.0

Behavior2/5

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

No annotations are provided, so the description bears full responsibility. It does not disclose whether the tool is read-only, requires authentication, or has rate limits. The only behavioral hint is the ID format.

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

Conciseness4/5

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

The description is very concise with no wasted words. However, it could include additional context without being verbose, such as mentioning the tool is for single-record retrieval.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and a simple single-parameter input, the description is minimally adequate. It doesn't mention error handling or that it returns a single run, but the context is sufficient for basic use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds value beyond the schema by noting that IDs start with 'rr_'. The schema already provides a detailed description, but the ID format note further clarifies parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it gets a research run by ID, which is unambiguous. However, it does not explicitly differentiate from sibling tools like delete_research_run that also operate by ID, though the verb 'get' implies retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus siblings like list_research_runs or search_research_runs. The description lacks context for appropriate use cases or prerequisites.

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

list_research_runsA

List research_runs. Filters by status (default: active). Returns newest first. IDs start with rr_.

ParametersJSON Schema

Name	Required	Default
`_name`	No	research_run
`limit`	No
`status`	No	active

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	Yes	Number of entities returned
`entities`	Yes

TDQS

A3.6/5.0

Behavior2/5

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

No annotations provided, so description must disclose behavior. States ordering and ID prefix, but does not mention read-only nature, auth requirements, rate limits, or empty result behavior.

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?

Extremely concise: two sentences plus a detail. Front-loaded with purpose, then adds key behaviors. No superfluous text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers main filters and ordering, but misses explaining '_name' parameter, limit behavior (max? paginated?), and read-only safety. Output schema exists, so return format is covered, but gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only 'status' is partially described as filter with default. No explanation for '_name' (default 'research_run') or 'limit' (default 50). Schema coverage is 0%, so description adds minimal value beyond schema.

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?

Clearly states it lists research runs with filtering by status and ordering. Distinct from siblings like get_research_run (single), search_research_runs (search), and delete_research_run (delete).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage via filters and ordering (use when you need a filtered, ordered list), but no explicit when-not or alternatives mentioned.

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

rebuild_indexA

Force a full rebuild of the relationship index from entity files. Use this if the index seems stale or after manual file edits.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.3/5.0

Behavior3/5

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

No annotations are provided, so the description carries the full burden. It mentions 'Force a full rebuild' implying it is potentially heavy, but lacks details on side effects, permissions, or safety considerations. Adequate but not thorough.

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?

Two sentences efficiently convey the action and usage context. No extraneous information; front-loaded with the purpose.

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?

Given that the tool has no parameters and a clear purpose, the description sufficiently covers what the tool does and when to use it. An output schema exists but the description does not need to detail return values for a rebuild operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so the description does not need to explain param semantics. The description adds context about the use case, meeting the baseline for no-parameter tools.

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 clearly states the verb 'rebuild' and the resource 'relationship index', with specificity about the source ('from entity files'). It is distinct from sibling tools which focus on research runs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit conditions for use: 'if the index seems stale or after manual file edits.' While it doesn't mention when not to use or alternatives, the tool is simple and such guidance is implied.

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

search_research_runsA

Search research_runs with text query and/or structured filters. Text query matches across all string fields (case-insensitive). Filters support: direct equality, $gt, $gte, $lt, $lte, $ne, $in, $contains, $exists. Sort with '-field' for descending. IDs start with rr_.

ParametersJSON Schema

Name	Required	Default
`sort`	No	-updated_at
`_name`	No	research_run
`limit`	No
`query`	No
`filter`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`count`	Yes	Number of entities returned
`entities`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

With no annotations, description carries full burden. Discloses case-insensitive search across all string fields, filter operators, sort syntax, and ID prefix ('rr_'). Lacks explicit read-only statement but implies safe operation.

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?

Two sentences, front-loaded with purpose. Every word adds value. No redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and presence of output schema, description is fairly complete: covers search behavior, filters, sorting, and default _name. Mentions ID prefix for identification. Slight gap in explaining lack of required parameters.

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?

Schema coverage is 0%, yet description adds meaning for all 5 parameters: query (free text), filter (object with operators), sort (descending with '-'), limit (default 20), _name (default 'research_run'). Compensates fully.

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?

Description clearly states the tool searches research_runs with text query and/or structured filters. It distinguishes itself from siblings like get_research_run (single), list_research_runs (likely unfiltered), and delete_research_run.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains when to use text query vs structured filters, and mentions sorting with '-field' for descending. Does not explicitly exclude alternatives, but context is clear enough for an agent to differentiate.

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

start_researchA

Run a research task on the given query. Supports MCP task augmentation — clients that advertise tasks.requests.tools.call may wrap the request with a task field to receive a CreateTaskResult and poll via tasks/get; clients that do not will block until the research completes and receive the full report inline. Either way, the server creates a research_run entity and updates its progress in real time so the Synapse UI can render live status. The worker typically takes ~60 seconds to 3 minutes and returns a markdown report. Pass title (3-8 word label) when you already know the topic — saves a background LLM call the server would otherwise make to derive one. Two ways to anchor research on existing material (use exactly one): seed_uri is a files:// URI the server reads itself via the host's ai.nimblebrain/host-resources extension — preferred when the host advertises the extension, since the agent doesn't have to load file bytes through its own context. seed_data is raw text passed inline by the agent — the universal fallback that works on every host. If the host doesn't support host-resources and seed_uri is provided, the tool returns a clear error telling the agent to retry with seed_data instead.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	The research query or topic.
`title`	No	Optional short label (3–8 words) for list rows and the detail-view heading. When omitted, the server generates one in the background via the FAST_LLM and patches the entity ~500ms later.
`seed_uri`	No	Optional `files://<id>` URI pointing at a workspace file the research should anchor on. Resolved server-side via the `ai.nimblebrain/host-resources` extension. Prefer this when the host advertises the extension — saves the agent's context budget.
`seed_data`	No	Optional raw text the research should anchor on. Universal fallback that works on hosts without the host-resources extension. Mutually exclusive with `seed_uri`.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.9/5.0

Behavior5/5

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

With no annotations provided, the description fully covers behavioral traits: the tool creates a 'research_run' entity, updates progress in real time, typical execution time (60s to 3 min), and return format (markdown report). It also explains the side effects of the 'title' parameter and the fallback logic for seed parameters.

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

Conciseness4/5

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

The description is fairly long but front-loaded with the main purpose. Every sentence adds value given the tool's complexity, though it could be slightly more concise by combining some details. Still well-structured with clear separation of topics.

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?

Given the tool's complexity (async, two modes, multiple parameters with fallback logic) and the existence of an output schema, the description provides complete context. It covers all necessary details for an agent to correctly select and invoke the tool, including practical tips and error scenarios.

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 schema coverage is 100%, the description adds significant meaning beyond the schema. It explains why 'title' is optional (saves a background LLM call), the trade-offs between 'seed_uri' and 'seed_data' (resource extension vs universal fallback), and the error handling for 'seed_uri' when the host doesn't support the extension.

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 clearly states the verb 'Run' and the resource 'research task on the given query'. It distinguishes itself from sibling tools (get/list/search/delete) by being the only tool that initiates research. The explanation of both blocking and task augmentation modes further clarifies its purpose.

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 provides explicit guidance on when to use the tool, including two execution modes (MCP task augmentation vs blocking), advice on using the 'title' parameter to save a background LLM call, and clear instructions for choosing between 'seed_uri' and 'seed_data' based on host capabilities. It also tells the agent to retry with 'seed_data' if 'seed_uri' fails.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

7 tool updatesv0.3.0Jul 30, 2026
- First observedadd_field
- First observeddelete_research_run
- First observedget_research_run
- First observedlist_research_runs
- First observedrebuild_index
- First observedsearch_research_runs
- First observedstart_research

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0

Disambiguation4/5

Tools are mostly distinct: get, list, search, delete, start for research runs, plus add_field and rebuild_index for supporting operations. However, start_research and the list/search tools could cause some confusion, as start_research creates a run while list/search find existing ones.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (e.g., get_research_run, add_field). No mixing of conventions or vague verbs.

Tool Count5/5

With 7 tools, the server is well-scoped for managing research runs and associated schema/index operations. Not too few or too many relative to the domain.

Completeness3/5

The server covers core operations for research runs (create via start_research, read via get/list/search, delete) but lacks an explicit update operation for runs. Schema management is limited to adding fields. This is a notable gap.

Maintenance

ActivityInactive

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
strata
ai.klavis
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Agent Orchestration Autonomous Agents Developer Tools
25,748
Parallel Task MCP AOAuth
ai.parallel
An MCP server for deep research or task groups
Autonomous Agents Agent Orchestration Research & Data
415
Reasoning Commons
io.github.chenyuan35
AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.
AI & Machine Learning Knowledge & Memory Autonomous Agents
2

Related MCP Servers

Gemini Research MCP Server
Search Research & Data AI & Machine Learning
machinemates-ai
A
license
A
quality
B
maintenance
MCP server for AI-powered research using Gemini. Provides fast grounded web search, deep autonomous research, URL extraction, and session management.
Updated 2 days ago (2026-09-04 07:30 UTC)
6
9
MIT
gpt-researcher-mcp
Search Text Summarization Research & Data
markchiang
A
license
B
quality
C
maintenance
Wraps the gpt-researcher tool as an MCP server, enabling automated web research, information summarization, and structured report generation via natural language queries.
Updated a year ago (2025-04-11 01:36 UTC)
2
45
MIT
deep-research
Agent Orchestration Autonomous Agents
troyhantech
A
license
Not graded
quality
C
maintenance
Enables deep research tasks using a multi-agent architecture that integrates any LLM and MCP tools. Available via MCP stdio, streamable HTTP, and SSE transports.
Updated 3 months ago (2026-06-15 01:55 UTC)
17
MIT
research
Web Scraping Search Research & Data
id5463
A
license
Not graded
quality
C
maintenance
Multi-purpose research MCP server integrating web search, deep research, web scraping, research methodology routing, and GPT Researcher report generation.
Updated 2 months ago (2026-07-10 05:02 UTC)
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/NimbleBrainInc/synapse-research'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

synapse-research

Quick Start

Architecture

UI retry flow

Configuration

Credentials (declared as user_config in manifest.json)

Routing (hard-coded in mcp_config.env)

Cost and latency

Data layout

Running locally

Install deps

Stdio (Claude Desktop, any MCP client)

HTTP (NimbleBrain platform)

Tests (keyless — no API keys required)

Tool reference

Contributing

Ecosystem

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

Credentials (declared as `user_config` in `manifest.json`)

Routing (hard-coded in `mcp_config.env`)