MCP Server for Claude

NeuralRepo exposes a remote MCP server that gives Claude direct access to your idea repository. Save, search, update, link, and delete ideas without ever leaving your conversation.

What Is MCP?

The Model Context Protocol is an open standard for connecting AI assistants to external tools and data. NeuralRepo implements an MCP server at:

https://neuralrepo.com/mcp/

When connected, Claude gains nine tools for managing your ideas: eight named tools plus code_mode, which reaches the rest of the API. Authorization is handled through OAuth 2.0 with PKCE, so your data stays secure.

Note

Every tool that takes an idea identifier takes the database id, never the #number shown in the web app and the CLI. The tools return both fields, so ask Claude for the id when you want to cross-reference an idea by hand. See Idea identifiers.

Setup

Claude.ai

1. Open Claude.ai and go to Settings ▸ Connectors.

2. Click Add custom connector.

3. Paste the NeuralRepo MCP URL:

   https://neuralrepo.com/mcp/

4. Save. On your next conversation, Claude will have access to NeuralRepo tools.

5. The first time Claude uses a tool, you will be prompted to authorize via OAuth. Sign in with your NeuralRepo account to grant access.

The same connector works in Claude Desktop and the Claude mobile apps once it is added to your account.

Claude Desktop

Add the following to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "neuralrepo": {
      "transport": "http",
      "url": "https://neuralrepo.com/mcp/"
    }
  }
}

On macOS, this file is located at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, it is at %APPDATA%\Claude\claude_desktop_config.json.

Restart Claude Desktop after saving. The OAuth prompt appears on first tool use.

Claude Code

Run the following command in your terminal:

claude mcp add --transport http neuralrepo https://neuralrepo.com/mcp/

On the next Claude Code session, NeuralRepo tools are available. OAuth authorization triggers automatically on first use.

Tip

The NeuralRepo dashboard has the same instructions built in, at Settings ▸ Integrations ▸ MCP Connector — including a Copy button for the URL and a Test connection button that reports back Connected or the error it hit.

OAuth Flow

NeuralRepo uses OAuth 2.0 with PKCE (S256) for MCP authorization:

1. Claude attempts to call a NeuralRepo tool.
2. The MCP client registers itself if it has not already — NeuralRepo supports Dynamic Client Registration at /mcp/register, and a registration is kept for 30 days.
3. The MCP client initiates an authorization request with a PKCE code challenge.
4. You are redirected to the NeuralRepo consent screen where you sign in (GitHub, Google, Apple, or magic link).
5. You grant Claude the requested scopes: ideas:read and ideas:write.
6. NeuralRepo issues an access token and a refresh token.
7. The MCP client stores the tokens and refreshes as needed.

Credential	Lifetime
Authorization code	10 minutes, single use
Access token	30 days
Refresh token	90 days, replaced on every refresh
Client registration	30 days

Scopes are enforced per tool. save_idea, update_idea, delete_idea, link_ideas, unlink_ideas, and code_mode all require ideas:write; everything else needs ideas:read.

Caution

Revoke MCP access from Settings ▸ Connections ▸ Connected MCP Clients in the NeuralRepo web dashboard. Two things to know: the Connections tab is Pro-only, so a Free account that has connected Claude has no in-app revoke button, and the group only appears once at least one client has completed the OAuth flow.

Available Tools

save_idea

Create a new idea in your repository. Ideas saved this way carry source: "claude-mcp".

Parameter	Type	Required	Description
title	string	Yes	Idea title (max 200 chars)
body	string	No	Full description in markdown (max 50,000 chars)
tags	string[]	No	Tags to apply (max 20, each max 50 chars)
source_url	string	No	URL where the idea originated (max 2,000 chars)
status	string	No	captured, exploring, building, shipped, shelved
parent_id	number	No	Parent idea id for sub-ideas — must exist, or the call fails

{
  "saved": true,
  "idea": {
    "id": 138,
    "number": 42,
    "title": "Browser extension for idea capture",
    "body": null,
    "status": "captured",
    "source": "claude-mcp",
    "source_url": null,
    "parent_id": null,
    "vectorize_id": null,
    "is_archived": 0,
    "created_at": "2026-03-24 10:30:00",
    "updated_at": "2026-03-24 10:30:00",
    "tags": ["chrome", "extension"]
  }
}

Embedding, duplicate detection, and auto-tagging run asynchronously after the tool returns, so vectorize_id is null in the response and any auto-applied tags land seconds later.

Caution

The Free plan’s 50-idea limit is reported as a success, not an error. Once a Free account holds 50 unarchived ideas, save_idea returns the plain sentence “You’ve captured 50 ideas on the free plan. Upgrade to Pro for unlimited ideas.” with no error flag — Claude will usually relay it, but nothing in the response shape says the save failed.

update_idea

Modify an existing idea, or change status and tags on up to 50 ideas at once.

Parameter	Type	Required	Description
id	number	Yes (single mode)	Idea id to update. Mutually exclusive with ids.
ids	number[]	Yes (bulk mode)	Up to 50 idea ids. Mutually exclusive with id.
title	string	No	New title — single mode only
body	string	No	New body — single mode only
status	string	No	New status
tags	string[]	No	Replace all tags
add_tags	string[]	No	Append tags without removing existing
remove_tags	string[]	No	Remove specific tags
link_to	object	No	Create a relation to another idea in the same call — single mode only. Sub-fields: idea_id (number, required), relation_type (string, required — one of related, blocks, inspires, parent, supersedes), note (string, optional).

tags cannot be combined with add_tags or remove_tags. Bulk mode rejects title, body, and link_to, and requires at least one of status or a tag operation.

Single mode returns the updated idea, plus relation_created when link_to was used:

{
  "updated": true,
  "idea": { "id": 138, "number": 42, "status": "building", "tags": ["chrome"] },
  "relation_created": { "id": 17, "relation_type": "related", "target_idea_id": 96 }
}

Bulk mode is not atomic — it reports per-idea outcomes and keeps going after a failure:

{
  "updated": 2,
  "errors": 1,
  "results": [
    { "id": 137, "status": "updated" },
    { "id": 138, "status": "updated" },
    { "id": 96, "status": "error", "error": "Idea 96 not found" }
  ]
}

delete_idea

Archive an idea. The row survives with is_archived = 1, and its vector is deleted from the search index.

Parameter	Type	Required	Description
id	number	Yes	Idea id to archive

{ "deleted": true, "id": 138, "title": "Browser extension for idea capture" }

Danger

There is no way back. Nothing in NeuralRepo — no tool, endpoint, CLI command, or dashboard control — clears is_archived, and archived ideas are excluded from every export. The tool’s own description says it “soft-deletes so it can be recovered later”; that is wrong. Treat delete_idea as permanent and ask Claude to confirm before calling it.

search_ideas

Search your ideas by meaning, or browse them by recency.

Parameter	Type	Required	Description
query	string	No	Search query, max 500 chars. Omit to browse/list.
status	string	No	Filter by status
tag	string	No	Filter by tag name
limit	number	No	Max results (max 100). Default 5 with a query; see below without one.
offset	number	No	Results to skip (browse mode)

With a query (search mode) — semantic search over your embeddings, reranked, with everything below your score threshold dropped:

{
  "query": "browser extension",
  "ideas": [
    { "id": 138, "number": 42, "title": "Browser extension for idea capture", "status": "captured", "tags": ["chrome"], "score": 0.92 }
  ],
  "search_type": "semantic"
}

search_type tells you which path answered:

Value	Meaning
semantic	Vector search returned matches above the threshold
fts_fallback	Semantic search returned nothing or errored, so keyword search answered — or a Free account has spent its 10 semantic searches for the month, in which case a notice field explains that
browse	No query was given

Note

This automatic keyword fallback is specific to the MCP tool and the AI agent. The REST API and the nrepo CLI return an empty result set instead of falling back. See Search.

Without a query (browse mode) — and this is the surprising one: with no limit and no offset, the tool auto-paginates and returns every idea you have, in pages of 100:

{
  "ideas": [ { "id": 138, "number": 42, "title": "Browser extension for idea capture", "status": "captured", "tags": ["chrome"] } ],
  "count": 1,
  "search_type": "browse"
}

Pass an explicit limit (or a non-zero offset) to get one page instead. That response adds offset, limit, and has_more, and its count is the total matching your filters, not the number of rows returned.

Filtering by a tag that does not exist is not an error — you get an empty list and a hint:

{ "ideas": [], "count": 0, "hint": "Tag \"chorme\" does not exist. Use list_tags to see available tags." }

get_idea

Retrieve a single idea with full details.

Parameter	Type	Required	Description
id	number	Yes	Idea id
include_context	boolean	No	Include related ideas, links, and duplicate detections (default false)

Without include_context you get the idea row plus tags, links, and relations. With it, the tool returns two content blocks: a Markdown project-context brief Claude can read directly, and the same data as JSON. Related ideas are deduplicated, so an idea reachable by two relation types appears once with a relation_types array.

list_tags

Returns all tags in your repository with idea counts. No parameters.

{
  "tags": [
    { "name": "chrome", "color": "#4285f4", "idea_count": 3 },
    { "name": "mobile", "color": null, "idea_count": 7 }
  ],
  "count": 2
}

link_ideas

Note

Pro only. The link_ideas tool requires a Pro plan.

Create typed relations between ideas, one at a time or up to 50 in a batch.

Parameter	Type	Required	Description
source_idea_id	number	Yes (single mode)	Source idea id
target_idea_id	number	Yes (single mode)	Target idea id
relation_type	string	No	related, parent, blocks, inspires, supersedes (default related)
note	string	No	Explanation of the relationship (max 500 chars)
links	object[]	Yes (bulk mode)	Up to 50 link objects with the same fields. Mutually exclusive with source_idea_id/target_idea_id.

parent reads source is a child of target, so linking 138 → 96 as parent makes 96 the parent. Cycles are refused outright for blocks and parent; supersedes cycles are allowed. Bulk mode returns { linked, errors, results } with a per-link outcome, so one bad pair does not kill the batch.

unlink_ideas

Note

Pro only. The unlink_ideas tool requires a Pro plan.

Remove a relation between ideas. Use get_idea with include_context: true to find relation IDs first.

Parameter	Type	Required	Description
relation_id	number	Yes	Relation ID to remove

The response is { "unlinked": true, "relation_id": 17 } whether or not a relation with that ID existed — a no-op and a real deletion look identical.

code_mode

Execute multi-step operations against the NeuralRepo API in a single call. Useful for workflows that combine search, filter, update, and link operations, or for accessing capabilities not exposed as discrete tools (merge ideas, manage duplicates, CRUD tags, attach URL links, get stats, develop specs, update relations).

Parameter	Type	Required	Description
code	string	Yes	Async JavaScript function body, max 10,000 characters. Calls snake_case functions on the neuralrepo object (e.g., neuralrepo.search_ideas(), neuralrepo.update_idea()).

The code runs in a sandboxed Worker with your user and plan applied, so plan gates and free-tier limits behave exactly as they do through the named tools.

Tips

Tip

Search before you save. Before asking Claude to save a new idea, ask it to search first. This avoids duplicates and often surfaces existing ideas you forgot about.

• Ask Claude to tag ideas as it saves them — “save this idea and tag it with mobile and mvp.”
• Use update_idea in bulk mode to retag or move a batch: “move all my browser extension ideas to exploring.”
• Use include_context: true on get_idea to see the full network around an idea.
• Ask for the id when you plan to use an idea elsewhere — the #42 Claude quotes back may be the display number.

Troubleshooting

Issue	Solution
OAuth prompt keeps appearing	Revoke the client in Settings ▸ Connections ▸ Connected MCP Clients (Pro) and re-authorize from scratch.
Connection timeout	Verify your network allows outbound HTTPS to neuralrepo.com. Corporate firewalls may block MCP transport.
”Not authorized” error	Your refresh token may have expired (90-day limit) or been revoked. Re-authorize via the OAuth flow.
”Insufficient scope”	The token was issued without ideas:write. Re-authorize and grant both scopes.
Tool not appearing in Claude	Ensure the MCP server is correctly configured. In Claude Code, run claude mcp list to verify.
Linking fails with “requires a Pro plan”	link_ideas and unlink_ideas are Pro-only. Every other tool works on Free.
”Idea N not found” for an idea you can see	You passed the display #number instead of the database id.
Rate limited	MCP requests count toward your daily API limit (100/day Free, 10,000/day Pro). Wait and retry.

Next Steps

Capture from Claude Day-to-day capture patterns once the connector is live.

Claude Code Pair the connector with the nrepo CLI for terminal workflows.

API Overview The REST surface code mode reaches, including idea identifiers and plan gates.

Plans & Pricing What Free and Pro each include, including relation writes.