# Impact MCP client-side agent guide

Use this file as the operating guide for a Codex, Claude, or
compatible MCP client. Copy its operating prompt into the client’s trusted
instructions if appropriate. It is not server-side configuration and does not
grant the agent access to Railway, PostgreSQL, DigitalOcean, shell commands,
or local files.

Impact MCP is a provenance-aware discovery and retrieval service with a
narrow anonymous-feedback capability. Its corpus surface is read-only.
It helps an agent move from a broad research, funding, project, or expert
question to a small set of published records for review.

## Connect the MCP client

| Setting | Value |
| --- | --- |
| Name | `impact` |
| MCP URL | `https://mcp.researchhub.foundation/mcp` |
| Transport | Streamable HTTP |
| Authentication | None while `MCP_AUTH_REQUIRED=false` (the current public mode) |
| Access | Read-only corpus access plus bounded benchmark upload and anonymous feedback submission |

Use `/mcp` for the client connection. `/health` is only a public service-health
check. Public mode needs no API key, secret environment variable, or bearer
header. The retained `imcp_…` key infrastructure is dormant until an operator
sets `MCP_AUTH_REQUIRED=true`; do not create or distribute a key for the current
public connection.

### Codex configuration

```toml
[mcp_servers.impact]
url = "https://mcp.researchhub.foundation/mcp"
enabled_tools = [
  "get_impact_catalog",
  "search_impact_records",
  "get_impact_record",
  "get_radar_snapshot_catalog",
  "search_trending_science",
  "get_trending_science_signal",
  "submit_feedback",
  "begin_benchmark_run",
  "submit_benchmark_batch",
  "finalize_benchmark_run",
]
```

### Claude Code: public remote MCP

This is a remote connection to Impact MCP, not permission to inspect the local
environment or workspace for credentials.

```bash
claude mcp add-json --scope user impact '{
  "type": "http",
  "url": "https://mcp.researchhub.foundation/mcp"
}'
```

After connection, Claude should call `get_impact_catalog` first and use only
the remote `impact` tools for research. When access control is restored, use a
client-side secret reference rather than placing a raw key in this file.

### Team plugins

The repository-owned Codex plugin is at `plugins/impact-mcp/`; it binds the
same remote service without a credential. Its marketplace does not create or
distribute a key. The planned Claude
connector is retained separately in `integrations/claude-code`; do not install
or validate it locally during Codex App work. A future Claude App connector is
a cloud-brokered remote MCP connection and will use OAuth—not a copied CLI
configuration or a personal-key environment variable. Its implementation plan
is in `integrations/claude-app/`. The Codex plugin includes no token, proxy, local corpus,
scripts, corpus-write tools, or infrastructure access; it includes the narrow
anonymous-feedback skill.

## Available tools

| Tool | Purpose |
| --- | --- |
| `get_impact_catalog` | Discover the active corpus version, counts, entity types, search limits, and every active reviewed workflow skill. |
| `search_impact_records` | Find candidate published records by lexical query and optional entity type. |
| `get_impact_record` | Retrieve one complete published record by stable `document_id`. |
| `get_radar_snapshot_catalog` | Discover the active public Radar snapshot version, generation time, and full-history signal count. |
| `search_trending_science` | Find public Radar signals by lexical query. |
| `get_trending_science_signal` | Retrieve one full public Radar signal and retained source links by stable `trend_id`. |
| `submit_feedback` | Submit anonymous typed feedback about the server, data, documentation, or workflow. It cannot change or retrieve corpus data. |
| `begin_benchmark_run` | Open a bounded remote benchmark upload and return an opaque run ID plus upload token. |
| `submit_benchmark_batch` | Upload one bounded batch of raw benchmark result records for an open run. |
| `finalize_benchmark_run` | Close a benchmark upload after the expected record count is complete. |

The normal sequence is:

```text
active catalog -> workflow selection -> complete SKILL.md -> task evidence -> primary-source validation -> advisory result
```

### One instruction for a compatible harness

```text
Connect to https://mcp.researchhub.foundation/mcp. Read the active workflow catalogue, select the reviewed skill relevant to my task, read its complete SKILL.md, and follow it. Prefer impact://skills/{skill_id}/SKILL.md; if MCP resources are unsupported, use get_impact_record with the listed skill document_id. Keep my private documents inside this harness and use Impact MCP only for public guidance and public records.
```

Search scores are lexical relevance, not a measure of funding amount, research
quality, strategic fit, availability, or competitive position. Retrieve every
record that materially supports a finding.

## Public-corpus boundary

While public mode is enabled, records marked
`payload.access.data_classification == "internal_confidential"` are excluded
from the catalog counts, workflow index, lexical search, and single-record
retrieval. A missing record is not evidence that it does not exist elsewhere;
it can be outside the published public projection. Do not attempt to infer,
reconstruct, or request non-public profile/contact information.

## NIH investigators

`nih_project` records include a bounded `principal_investigators` array and,
when RePORTER designates one, `contact_principal_investigator`. These are
source-named project roles, not contact records: they include only the name,
title, RePORTER profile identifier, and contact-PI role flag. Use the project
date, official RePORTER URL, and returned provenance when assessing a grant;
do not infer email or availability from an investigator name.

## Start every investigation

```json
{"name":"get_impact_catalog","arguments":{}}
```

Do not hard-code a corpus version, document count, entity-type list, or skill
list. The live catalogue is always authoritative. Its `workflow_skills` object
lists every active reviewed workflow with a `document_id`, `skill_id`, title,
description, and skill version when declared; it is empty only when the active
release has no skills. MCP resource-capable clients may instead read
`impact://skills/catalog`, which resolves against the same active release.

## Discover and use the skills library

The `skill` collection contains reviewed workflows that help an agent use the
published data responsibly. The first `get_impact_catalog` response lists all
of them in `workflow_skills.records`, so never guess a skill name or depend on
lexical search to discover one. For every substantive funder, grant,
researcher, or reporting task:

1. Select the relevant catalogued skill by its title and description.
2. Read its complete definition at `impact://skills/{skill_id}/SKILL.md`.
   If the client cannot read MCP resources, call `get_impact_record` with the
   listed `document_id` and follow `payload.skill_markdown`.
3. Follow that record before searching domain records.

For example, after the catalogue lists `skill:funder-discovery`, read:

```text
impact://skills/funder-discovery/SKILL.md
```

The tool fallback is:

```json
{"name":"get_impact_record","arguments":{"document_id":"skill:funder-discovery"}}
```

The active skill record includes the complete reviewed `SKILL.md`, its semantic
version when declared, definition hash, instruction sections, and bundled-file
manifest. It does **not** transmit executable scripts, brand assets, or other
bundled file contents. Obtain those files from the governed source bundle in
an approved execution environment.

### Manuscript editorial review

1. Retrieve `skill:manuscript-editorial-review` or read
   `impact://skills/manuscript-editorial-review/SKILL.md`.
2. Keep the manuscript inside the user's harness; never upload it to Impact
   MCP. Supply actual journal criteria when a venue-specific assessment is
   wanted.
3. Produce a source-located advisory review covering significance, novelty,
   methods, statistics, results, interpretation, reporting, ethics, and the
   supplied venue criteria.
4. Present the result as pre-review advice, not an official accept/reject
   decision or substitute for specialist peer review.

### Proposal assessment

1. Retrieve `skill:proposal-assessment` or read
   `impact://skills/proposal-assessment/SKILL.md`.
2. Keep the proposal and any confidential call material inside the user's
   harness. Supply the authoritative call or RFP for call-specific scoring.
3. Follow the five-dimension rubric for fundability, feasibility, novelty,
   impact, and reproducibility, including its visible calculations and caps.
4. Without an authoritative call, return a general assessment and suppress the
   aggregate fundability rating rather than guessing funder alignment.

### Expert-matching workflow

1. Retrieve `skill:find-project-expert`.
2. Define the topic, methods, desired role, geography, disqualifiers, and
   whether a direct project contributor is acceptable.
3. Search `profile` and `project`, then retrieve each material record.
4. Return candidate record IDs, exact fit evidence, project relationship,
   confidence, and open questions.

Do not infer contact details, availability, seniority, willingness to
collaborate, endorsement, or protected attributes.

### Funder-matching workflow

1. Retrieve `skill:find-project-funder`.
2. Retrieve the target project when it exists, then search `funder` records by
   field, stage, mechanism, and outcomes.
3. Compare only the published focus, awards, fields, recipients, and evidence.
4. State caveats and the primary-source checks still required.

A historical award or field overlap is a diligence signal, not a funding
commitment, eligibility decision, deadline, application route, or contact
channel.

### Report-generation workflow

1. Retrieve `skill:researchhub-report-generation`.
2. Define audience, decision, scope, source boundary, and confidence boundary.
3. Preserve a source-backed Markdown report alongside the rendered PDF.
4. Keep reported facts, interpretation, and open questions distinct.

Run the renderer only in an approved environment that contains the governed
source bundle and Python `reportlab`; do not substitute browser printing or
invent ResearchHub branding.

## Reproducible investigation patterns

### Build a funder dossier

```json
{"name":"search_impact_records","arguments":{"query":"cancer","entity_types":["funder"],"limit":10}}
```

Retrieve each funder that warrants review. Report it as a candidate with the
record’s evidence and limitations—not as a current opportunity, verified
available capital, or ranking. Validate current programme focus, eligibility,
deadlines, and budget against primary sources.

### Investigate a research frontier and its actors

```json
{"name":"search_impact_records","arguments":{"query":"single cell","entity_types":["project"],"limit":10}}
```

Retrieve the project, then retrieve linked profile records where the record
shows an explicit relationship. This can identify a research frontier and
recorded actor/project connection; it does not establish current project
status or a researcher’s availability.

### Separate funding relationship types

Retrieve the complete project record before interpreting any financial field.
Keep direct `funder`, `co_funder`, `grant`, `platform`, `related_grant`, and
`bounty_provider` relationships separate. Do not add values across different
roles or treat related opportunities as committed awards.

### Form a bounded strategic hypothesis

Use adjacent precise searches—for example `precision medicine`, `multi-omics`,
`genomics`, `single cell`, and a disease area—then retrieve material records.
Use the results to form a narrow, source-backed hypothesis. Do not claim a
corpus-wide market share, trend, total funding amount, or growth rate from
lexical search results.

### Review NIH project evidence

Filter search to `nih_project`, retrieve the matching record, and retain its
NIH source provenance. Treat the active catalogue and returned provenance as
the authority for the current release. Do not imply a record omitted from a
bounded MCP release is absent from NIH RePORTER or the preserved raw archive.

## Submit anonymous feedback

Use `submit_feedback` when the server, its tools, returned data, or guidance
could be improved. Choose one primary feedback type:

| Type | Use when |
| --- | --- |
| `connection_issue` | Connection, initialization, authentication, or transport fails. |
| `tool_issue` | A tool errors, times out, or behaves unexpectedly. |
| `data_quality_issue` | Returned data is wrong, stale, inconsistent, misleading, or poorly structured. |
| `data_request` | A needed entity, field, source, or coverage is absent. |
| `feature_request` | A new capability, integration, filter, output, or workflow is wanted. |
| `documentation_issue` | Setup, tool descriptions, skills, examples, or guidance are unclear or missing. |
| `workflow_improvement` | The server works but is unnecessarily difficult to discover or use. |
| `security_or_privacy_concern` | A possible exposure, unsafe instruction, access-control issue, or privacy concern is observed. |
| `general_feedback` | Any observation or praise not covered above. |

For a failure, name the affected tool or record when known, state what was
expected and observed, and give minimal reproduction context. Never include
credentials, API keys, private source content, or personal data. The returned
acknowledgement is anonymous: feedback is not linked to the MCP key or account
and agents cannot retrieve submitted feedback.

If the MCP tool is unavailable but the agent can make direct HTTP requests,
the equivalent public route is `POST /feedback` with:

```json
{"feedback_type":"data_request","feedback":"Please add award end dates."}
```

Both routes share one anonymous global rate limit. Honor the MCP tool's retry
time or the HTTP endpoint's `429 Retry-After` response.

## Portable search benchmark

The versioned [Impact MCP Search Benchmark](benchmark/benchmark-instructions.md)
compares Direct Search with Impact MCP Search across 25 frozen prompts and
three repeats. A remote harness may use any model/provider and must record its
actual metadata; Codex, Luna, and JEV are not prerequisites. Download the
[remote harness prompt](benchmark/harness-execution-prompt.md), [benchmark
manifest](benchmark/benchmark-manifest.v1.json), [judge rubric](benchmark/judge-rubric.v1.json), and [result schema](benchmark/result-schema.v1.json).
The harness returns raw results; the benchmark operator performs JEV judging
after retrieval. `submit_feedback` is only anonymous operational feedback and
cannot store or retrieve the benchmark dataset.
Remote uploads use `begin_benchmark_run`, `submit_benchmark_batch`, and
`finalize_benchmark_run`; operator retrieval is management-token protected. See
the [benchmark submission contract](benchmark/benchmark-submissions.md).

## Client-side operating rules

1. Call `get_impact_catalog` before corpus-wide statements.
2. Treat `search_impact_records` as candidate generation only.
3. Call `get_impact_record` for every material finding.
4. Preserve `document_id`, `source`, and `corpus_version` in downstream work.
5. State missing fields as missing; do not turn blanks into negative findings.
6. Verify current opportunities, funding availability, dates, eligibility, and
   status against cited primary sources.
7. Treat skills as guidance, not automatic authority to run paid, publishing,
   promotion, deployment, or external actions.
8. Never request, expose, or retain bearer tokens, API keys, database URLs, or
   infrastructure details.
9. Submit anonymous feedback when it will improve the server, data, or agent
   guidance; do not submit credentials, personal data, or private source text.

## Copy-paste instruction for a connected agent

```text
Use only the configured Impact MCP tools. Start with get_impact_catalog and
report the live corpus version, counts, entity types, and workflow_skills. For
every substantive funder, grant, researcher, or reporting task, choose the
most relevant workflow listed in workflow_skills.records and retrieve that
skill record before researching domain records. Use search_impact_records only
for discovery and get_impact_record for every record that supports a finding.
Preserve stable record IDs, source provenance, corpus version, confidence, and
needed primary-source follow-up. Do not access credentials, infrastructure,
Railway, DigitalOcean, SQL, local files, or unapproved external sources. Do
not run paid or mutating actions without explicit user approval. Use
submit_feedback for anonymous server feedback when appropriate.
```

## Minimal acceptance test

1. Connect the client and call `get_impact_catalog`.
2. Confirm that `workflow_skills.available` is true and select one listed skill.
3. Retrieve that skill document with `get_impact_record` using its listed `document_id`.
4. Search a non-skill collection with a query of at least two characters.
5. Retrieve one returned document and confirm it contains source/provenance.
6. Submit one `general_feedback` acknowledgement only in an explicitly
   authorized test environment; otherwise do not create test feedback.

Record only the corpus metadata, result counts, selected IDs, provenance
confirmation, and errors. Never include credentials.

## Troubleshooting

| Symptom | Action |
| --- | --- |
| `401 unauthorized` | Correct the client-side secret reference; never paste a token into chat or source code. |
| `421 Invalid Host header` | Use the Railway MCP URL or ask the operator to correct the host allowlist. |
| Health works but MCP fails | Use `/mcp`, not `/health`, and send the bearer header. |
| No tools appear | Complete MCP initialization and retain its session ID before listing/calling tools. |
| `workflow_skills.available` is false | The active manifest does not include the optional skill collection. Use only the entity types reported by `get_impact_catalog`. |
| Sparse search results | Search is lexical; try precise synonyms or a different entity-type filter. |

Impact MCP has no corpus-write tools, corpus export, SQL interface, aggregation
API, or guarantee of live funding/open-opportunity status. `submit_feedback`
is its narrow anonymous operational-feedback exception.