Physicist MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Physicist MCP Server find subatomic particles similar to the Higgs boson"
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.
Physicist Model Context Protocol (MCP) Server
A Model Context Protocol (MCP) server providing deep LLM-agent tool, resource, and prompt integrations with Physicist — an open-source computational research platform and quantitative analytical laboratory for comparative particle physics, subatomic particles, and quantum state manifolds.
Overview
The physicist-mcp server enables AI agents (Claude Code, Cursor, Gemini CLI, Antigravity) to query, manipulate, cluster, and synthesize physics domain models directly over standard input/output (stdio):
51 Registered MCP Tools across 8 functional modules (Search, Particle Groups, Subatomic Particles, Quantum States, Clustering, Synthesis Reports, Background Jobs, and System Diagnostics).
4 Registered MCP Resources exposing read-only live platform status, catalogs, cluster snapshots, and markdown monographs.
2 MCP Prompt Templates for comparative particle physics studies and quantum cluster synthesis monographs.
1024-dimensional semantic manifold querying via PostgreSQL
pgvectorHNSW indexes.
Related MCP server: Terminal Session Manager
Architectural Mapping
Tier / Domain | Model | Table Name | MCP Module / Tools |
Tier 1 | Particle Groups / Families |
|
|
Tier 2 | Subatomic Particles / Hadrons |
|
|
Tier 3 | Quantum States / Eigenmodes |
|
|
Clustering | 15-Level Agglomerative |
|
|
Synthesis | Multi-Stage Map-Reduce |
|
|
Global Search | Cross-Catalog pgvector | Multi-table |
|
Platform | Jobs & System Info | Multi-service |
|
Installation & Setup
Prerequisites
Node.js 20+
Running instance of Physicist (
http://localhost:3000)
Build
git clone https://github.com/leouofa/physicist-mcp.git
cd physicist-mcp
npm install
npm run buildRunning the Server
# Run with defaults (http://localhost:3000/api/v1)
node dist/index.js
# Or with custom options
node dist/index.js --url http://localhost:3000/api/v1 --timeout 90000Configuration
Configuration options can be supplied via environment variables or CLI flags:
Environment Variable | CLI Flag | Default | Description |
|
|
| Base URL of Physicist REST API |
|
| (none) | Optional Bearer token for authentication |
|
|
| HTTP request timeout in milliseconds |
MCP Host Integration
Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"physicist": {
"command": "node",
"args": ["/path/to/physicist-mcp/dist/index.js"],
"env": {
"PHYSICIST_API_URL": "http://localhost:3000/api/v1"
}
}
}
}Antigravity (~/.gemini/antigravity/mcp_config.json)
{
"mcpServers": {
"physicist": {
"command": "node",
"args": ["/Users/leonid/src/physicist-mcp/dist/index.js"],
"env": {
"PHYSICIST_API_URL": "http://localhost:3000/api/v1"
}
}
}
}Tool Catalog
1. Global Search & Manifolds
search: Unified cross-catalog semantic (1024-d cosine similarity) or keyword search across subatomic particles and quantum states.find_counterparts: Find nearest physical counterparts or symmetry analogs using 1024-dimensional pgvector cosine distance.
2. Tier 1: Particle Groups
list_particle_groups: List taxonomic families with particle counts.get_particle_group: Retrieve a particle group with nested subatomic particles.create_particle_group: Register a new particle group.update_particle_group: Update name or theoretical description.delete_particle_group: Cascade delete a particle group.upsert_particle_groups_batch: Bulk upsert particle groups by name.populate_particle_groups: Trigger LLM discovery of particle groups.populate_particle_group_subatomic_particles: Trigger LLM discovery of particles for a group.
3. Tier 2: Subatomic Particles
list_subatomic_particles: Filter particles by group, themes, embedding status, and search keywords.get_subatomic_particle: Retrieve particle profile with vector embedding and child quantum states.create_subatomic_particle: Create a new subatomic particle.update_subatomic_particle: Update physical attributes or reassign particle group.delete_subatomic_particle: Cascade delete a particle.upsert_subatomic_particles_batch: Bulk upsert particles under a particle group.generate_subatomic_particle_embedding: Generate 1024-d pgvector embedding vector.populate_subatomic_particle_quantum_states: Trigger LLM discovery of quantum states for a particle.populate_subatomic_particles_bulk: Bulk discover particles across all groups.
4. Tier 3: Quantum States
list_quantum_states: Filter quantum states and eigenmodes.get_quantum_state: Retrieve quantum state details and parent particle metadata.create_quantum_state: Create a new quantum state or eigenmode.update_quantum_state: Update quantum numbers or descriptions.delete_quantum_state: Delete a quantum state.upsert_quantum_states_batch: Bulk upsert quantum states under a particle.generate_quantum_state_embedding: Generate 1024-d vector embedding.populate_quantum_states_bulk: Bulk discover quantum states.
5. Clustering & Snapshots
compute_clusters: Compute live connected-components vector clusters across 15 granularity levels without persisting.create_cluster_snapshot: Compute clustering and freeze it immediately into an immutable snapshot.list_cluster_snapshots: List frozen snapshots.get_cluster_snapshot: Retrieve snapshot with groups, members, and reports.delete_cluster_snapshot: Delete a cluster snapshot.list_cluster_groups: List archetype groups in a snapshot.get_cluster_group: Retrieve a single archetype cluster group with member entities.
6. Synthesis Reports
list_cluster_reports: List multi-phase synthesis reports.get_cluster_report: Retrieve scholarly report content, progress, and intermediate summaries.create_cluster_report: Initiate a 2-Phase Map-Reduce synthesis monograph.delete_cluster_report: Delete a cluster report.generate_deep_synthesis: Upgrade or run a 3-Phase Hierarchical Deep Synthesis.list_report_summaries: List Phase 1 per-cluster summaries.get_report_summary: Retrieve a single Phase 1 summary.list_report_sub_reports: List Phase 2 batch syntheses.get_report_sub_report: Retrieve a single Phase 2 batch analysis.
7. Background Jobs
list_jobs: List recent ActiveJob/Sidekiq background tasks.get_job_status: Inspect job status, progress, and results.wait_for_job: Poll a background task until completion or failure.
8. Platform & Diagnostics
get_platform_status: Platform health, record counts, and LLM configuration.get_settings: Embedding completion metrics and LLM presets.update_context_window: Dynamically adjust LLM context window token size.trigger_bulk_embeddings: Enqueue bulk embedding calculations.get_openapi_spec: Retrieve OpenAPI 3.1 specification.
MCP Resources
URI | Format | Description |
|
| System health, entity counts, LLM models, and context window budgets. |
|
| Full catalog of particle groups and subatomic particle counts. |
|
| Frozen cluster snapshot including discovered archetype groups and members. |
|
| Full academic monograph generated by the synthesis pipeline. |
MCP Prompts
comparative_particle_analysis: Rigorous comparative particle physics analysis between two entities across particle groups using gauge invariants, spin-statistics, and semantic manifold distance.quantum_cluster_monograph: Academic monograph draft addressing a research inquiry grounded in a frozen snapshot's archetype clusters.
Testing
# Run unit test suite
npm test
# Run tests in watch mode
npm run test:watchLicense
MIT License. Copyright (c) 2026 Leonid Medovyy.
Available Tools
51 toolscompute_clustersB
Compute live connected-components vector clusters for SubatomicParticles or QuantumStates across particle groups without modifying the database.
Inputs: force, level, target_type, full_coverage.
create_cluster_reportB
Initiate a 2-Phase Map-Reduce synthesis report on a frozen cluster snapshot.
Inputs: prompt (required), cluster_snapshot_id (required).
create_cluster_snapshotB
Compute connected-components clustering and freeze it immediately into an immutable database snapshot.
Inputs: level (required), title (required), target_type (required), full_coverage.
create_particle_groupC
Create a new particle group record in the catalog.
Inputs: name (required), description.
create_quantum_stateC
Create a new quantum state or eigenmode under a subatomic particle.
Inputs: name (required), subatomic_particle_id (required), themes, description.
create_subatomic_particleC
Create a new subatomic particle record in Physicist.
Inputs: name (required), particle_group_id (required), themes, description.
delete_cluster_reportB
Delete a cluster report and its intermediate summaries.
Inputs: id (required).
delete_cluster_snapshotB
Delete a frozen cluster snapshot along with its cascaded cluster groups and synthesis reports.
Inputs: id (required).
delete_particle_groupA
Delete a particle group and its cascaded subatomic particles and quantum states.
Inputs: id (required).
delete_quantum_stateC
Delete a quantum state from the catalog.
Inputs: id (required).
delete_subatomic_particleB
Delete a subatomic particle and its cascaded quantum states.
Inputs: id (required).
find_counterpartsA
Find nearest physical counterparts or symmetry analogs to a specified subatomic particle or quantum state using 1024-dimensional pgvector cosine distance.
Inputs: id (required), entity_type (required), limit, include_embedding, +2 more.
generate_deep_synthesisC
Upgrade or run a 3-Phase Hierarchical Deep Synthesis report over a cluster snapshot with intermediate batch aggregation.
Inputs: report_id (required), batch_size.
generate_quantum_state_embeddingC
Generate or regenerate a 1024-dimensional semantic embedding vector for a quantum state.
Inputs: id (required), sync.
generate_subatomic_particle_embeddingC
Generate or regenerate a 1024-dimensional semantic embedding vector for a single subatomic particle.
Inputs: id (required), sync.
get_cluster_groupB
Retrieve details of a specific archetype cluster group with all member subatomic particles or quantum states.
Inputs: id (required), include_members.
get_cluster_reportB
Retrieve complete scholarly physics report content, progress percentage, markdown monograph, and intermediate summaries.
Inputs: id (required), include_summaries, include_sub_reports.
get_cluster_snapshotC
Retrieve details of a frozen cluster snapshot including member groups and generated synthesis reports.
Inputs: id (required), include_groups, include_members, include_reports.
get_job_statusB
Check the status, progress, and result of an ActiveJob/Sidekiq background task.
Inputs: job_id (required).
get_openapi_specA
Retrieve the raw OpenAPI 3.1 specification for the Physicist API.
Inputs: no named parameters.
get_particle_groupA
Retrieve details of a single particle group including its subatomic particles.
Inputs: id (required), include_subatomic_particles.
get_platform_statusA
Get overall platform health, catalog entity counts, embedding coverage stats, and active LLM configuration.
Inputs: no named parameters.
get_quantum_stateC
Retrieve details of a single quantum state including parent subatomic particle and particle group metadata.
Inputs: id (required), include_embedding.
get_report_sub_reportC
Retrieve a single Phase 2 batch analysis.
Inputs: id (required).
get_report_summaryC
Retrieve a single Phase 1 per-cluster scholarly summary.
Inputs: id (required).
get_settingsA
Get embedding completion metrics for SubatomicParticles and QuantumStates, active embedding/LLM parameters, and context window presets.
Inputs: no named parameters.
get_subatomic_particleB
Retrieve details of a single subatomic particle including its particle group and child quantum states.
Inputs: id (required), include_embedding, include_quantum_states.
list_cluster_groupsB
List all archetype cluster groups belonging to a specific frozen snapshot.
Inputs: cluster_snapshot_id (required), include_members.
list_cluster_reportsC
List generated multi-phase comparative particle physics and quantum state manifold synthesis reports.
Inputs: limit, offset, status, is_detailed, +2 more.
list_cluster_snapshotsC
List frozen archetype cluster snapshots in Physicist.
Inputs: limit, offset, target_type, include_groups.
list_jobsB
List recent asynchronous background jobs (embedding calculations, LLM discoveries, synthesis reports).
Inputs: limit.
list_particle_groupsB
List particle groups (taxonomic families, structural sectors, supermultiplets) registered in Physicist with subatomic particle counts.
Inputs: q, limit, offset, include_subatomic_particles.
list_quantum_statesB
List quantum states and eigenmodes registered in Physicist with filtering by subatomic particle, particle group, themes, and embedding status.
Inputs: q, limit, theme, offset, +4 more.
list_report_sub_reportsB
List all Phase 2 intermediate batch analyses belonging to a detailed synthesis report.
Inputs: cluster_report_id (required).
list_report_summariesB
List all Phase 1 per-cluster analyses belonging to a synthesis report.
Inputs: cluster_report_id (required).
list_subatomic_particlesB
List subatomic particles registered in Physicist with filtering by particle group, themes, embedding status, and search keywords.
Inputs: q, limit, theme, offset, +5 more.
populate_particle_groupsC
Trigger LLM discovery to populate major particle groups and families with physics descriptions.
Inputs: sync.
populate_particle_group_subatomic_particlesC
Discover and populate subatomic particles for a specific particle group via LLM generation.
Inputs: id (required), sync.
populate_quantum_states_bulkC
Bulk trigger discovery of quantum states across all subatomic particles under an optional subatomic particle scope.
Inputs: sync, subatomic_particle_id.
populate_subatomic_particle_quantum_statesB
Discover and populate quantum states, eigenmodes, and helicity manifolds for a subatomic particle via LLM analysis.
Inputs: id (required), sync.
populate_subatomic_particles_bulkA
Bulk trigger discovery of subatomic particles across one or all particle groups via background job.
Inputs: sync, particle_group_id.
searchB
Unified cross-catalog semantic or keyword search across subatomic particles and quantum states in the Physicist comparative physics manifold.
Inputs: q (required), mode, limit, target_type.
trigger_bulk_embeddingsB
Enqueue bulk embedding generation for all SubatomicParticles or QuantumStates.
Inputs: model_type (required), only_missing.
update_context_windowC
Dynamically update the active LLM context window token size.
Inputs: context_window (required).
update_particle_groupC
Update an existing particle group's name or description.
Inputs: id (required), name, description.
update_quantum_stateC
Update an existing quantum state's attributes.
Inputs: id (required), name, themes, description, +1 more.
update_subatomic_particleC
Update an existing subatomic particle's attributes.
Inputs: id (required), name, themes, description, +1 more.
upsert_particle_groups_batchA
Batch insert or update particle groups matching case-insensitively on name.
Inputs: particle_groups (required).
upsert_quantum_states_batchB
Batch insert or update quantum states for a specific subatomic particle matching on lower(name).
Inputs: quantum_states (required), subatomic_particle_id (required).
upsert_subatomic_particles_batchA
Batch insert or update subatomic particles under a specific particle group matching on lower(name).
Inputs: particle_group_id (required), subatomic_particles (required).
wait_for_jobA
Poll a background job until completion or failure with configurable timeout.
Inputs: job_id (required), timeout_ms, poll_interval_ms.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 51 tools
Many tools share the 'populate' verb with subtly different scopes (populate_particle_groups, populate_particle_group_subatomic_particles, populate_subatomic_particles_bulk, populate_subatomic_particle_quantum_states, populate_quantum_states_bulk), and generate_deep_synthesis vs create_cluster_report vs compute_clusters vs create_cluster_snapshot require careful reading to distinguish. Descriptions do disambiguate most cases, but an agent can easily pick the wrong populate/synthesis variant.
The dominant pattern is snake_case verb_noun (list_/get_/create_/update_/delete_/upsert_/populate_/generate_), applied consistently across resources. Minor deviations exist — bare 'search', 'find_counterparts', 'compute_clusters', and 'wait_for_job' — where verb style shifts, but overall the convention is predictable.
51 tools is heavy even for a multi-resource domain with particles, quantum states, groups, clustering, reports, jobs, and settings. Several capabilities could be folded into parameters (e.g. consolidating the five populate_* variants or the report summary/sub-report list/get pairs), and the sheer surface raises selection cost for an agent.
The surface covers full CRUD plus batch upserts for particle groups, subatomic particles, and quantum states, along with embeddings, clustering, report lifecycle, job polling, and platform settings. Gaps are minor: no job cancellation, no report update/regeneration, and snapshot lifecycle lacks an export/merge operation, but core workflows are covered.
Maintenance
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Task management your AI agents can actually run. One line becomes a context-ready task over MCP.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceEnables AI agents to perform auditable A* reasoning, import world graphs, incorporate physical carrier constraints, and maintain a learning knowledge base through a zero-dependency local MCP stdio service.MIT
- FlicenseBqualityCmaintenanceEnables AI agents to create and control persistent terminal sessions, run and monitor asynchronous jobs, page through ordered event history, and resolve registered device connection details without exposing stored secrets. Exposes 15 MCP tools over stdio that mirror a REST API, keeping session state alive independently of the agent that started it.15-
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to query product footprints, inspect transport activity data, and submit events from iLEAP-conformant endpoints through natural language, using MCP tools over Streamable-HTTP or stdio.1MIT
- AlicenseAqualityCmaintenanceEnables AI agents to discover accessible quantum instances and backends, simulate circuits locally, preview transpiled circuits, submit Sampler or Estimator jobs, and inspect or cancel runtime jobs via typed MCP tools.10MIT