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., "@Statesman MCP Server find countries with a geopolitical profile similar to Singapore"
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.
A production-ready Model Context Protocol (MCP) server interfacing with the Statesman computational laboratory for comparative geopolitics, statecraft, and urban power centers (/api/v1 REST API).
Statesman MCP allows AI agents (in Antigravity, Claude Desktop, Cursor, and custom agent harnesses) to seamlessly navigate, search, cluster, and synthesize cross-continental geopolitical catalogs, 1024-dimensional pgvector cosine distance manifolds, and multi-stage LLM synthesis monographs.
+---------------------------------------+
| AI Agent (Claude, Antigravity, etc.) |
+-------------------+-------------------+
|
stdio | JSON-RPC
v
+---------------------------------------+
| Statesman MCP Server |
| - 51 Tools (Search, CRUD, ML) |
| - 4 Resources (Status, Reports) |
| - 2 Geopolitical Analysis Prompts |
+-------------------+-------------------+
|
HTTP | REST (/api/v1)
v
+---------------------------------------+
| Statesman API (Rails) |
| - pgvector 1024-dim Manifold |
| - Connected-Components Clustering |
| - Multi-phase Synthesis Engine |
+---------------------------------------+search: Unified semantic (pgvector) or keyword search across sovereign countries and strategic cities.
find_counterparts: Identifies nearest structural geopolitical or urban counterparts to any country or city using 1024-dimensional vector cosine distance (with optional continent or country scoping).
Continents (8 tools): list_continents, get_continent, create_continent, update_continent, delete_continent, upsert_continents_batch, populate_continents, populate_continent_countries.
Countries (9 tools): list_countries, get_country, create_country, update_country, delete_country, upsert_countries_batch, generate_country_embedding, populate_country_cities, populate_countries_bulk.
Cities (8 tools): list_cities, get_city, create_city, update_city, delete_city, upsert_cities_batch, generate_city_embedding, populate_cities_bulk.
compute_clusters: Dynamically calculates connected-components vector clusters across Country or City manifolds with configurable granularity levels (1–15) and zero-singleton full_coverage absorption without modifying the database.
create_cluster_snapshot: Computes and freezes clustering into an immutable database snapshot.
list_cluster_snapshots, get_cluster_snapshot, delete_cluster_snapshot, list_cluster_groups, get_cluster_group.
create_cluster_report: Triggers a 2-Phase Map-Reduce synthesis report on a snapshot with a custom geopolitical or urban research inquiry.
generate_deep_synthesis: Initiates a 3-Phase Hierarchical Deep Synthesis monograph, grouping Phase 1 summaries into intermediate batch analyses.
list_cluster_reports, get_cluster_report, delete_cluster_report, list_report_summaries, get_report_summary, list_report_sub_reports, get_report_sub_report.
get_job_status, list_jobs: Inspect ActiveJob/Sidekiq lifecycle states.
wait_for_job: Polls asynchronous operations until completion or failure with configurable intervals and timeouts.
get_platform_status: Platform health, entity counts (continents, countries, cities), embedding coverage stats, and active LLM configuration.
get_settings, update_context_window, trigger_bulk_embeddings, get_openapi_spec.
Related MCP server: knowledge-base-server
Directly inspectable URIs that AI agents can mount into context:
statesman://status: Platform health, entity metrics, and active LLM/embedding models.
statesman://continents: Catalog overview of all registered continents and sovereign country counts.
statesman://snapshots/{id}: Detailed cluster groups and member states/cities of a frozen snapshot.
statesman://reports/{id}: Full compiled markdown text of a scholarly synthesis monograph.
comparative_statecraft_analysis: Structured inquiry comparing two sovereign countries or strategic cities across continents using statecraft themes and semantic similarity.
geopolitical_cluster_synthesis: Guides the model to draft an academic monograph based on frozen cluster snapshots.
Node.js >= 18.0.0
A running Statesman instance (default: http://localhost:3000/api/v1)
git clone https://github.com/leouofa/statesman-mcp.git
cd statesman-mcp
npm install
npm run buildCreate a .env file or export environment variables:
STATESMAN_API_URL=http://localhost:3000/api/v1
# STATESMAN_API_KEY=your_optional_token
STATESMAN_TIMEOUT_MS=60000Add to your claude_desktop_config.json:
{
"mcpServers": {
"statesman": {
"command": "node",
"args": [
"/absolute/path/to/statesman-mcp/dist/index.js"
],
"env": {
"STATESMAN_API_URL": "http://localhost:3000/api/v1"
}
}
}
}Add to your client configuration:
{
"mcpServers": {
"statesman": {
"command": "npx",
"args": ["-y", "tsx", "/absolute/path/to/statesman-mcp/src/index.ts"],
"env": {
"STATESMAN_API_URL": "http://localhost:3000/api/v1"
}
}
}
}Usage:
statesman-mcp [options]
Options:
-u, --url <url> Statesman API base URL (default: http://localhost:3000/api/v1)
-k, --api-key <key> Optional API key / Bearer token
-t, --timeout <ms> Request timeout in milliseconds (default: 60000)
-h, --help Display help message# Run unit and integration test suite
npm test
# Run tests in watch mode
npm run test:watch
# Compile TypeScript
npm run build
# Start server directly in development
npm run devMIT © Leonid Medovyy
Compute live connected-components vector clusters for Countries or Cities across continents without modifying the database.
Inputs: force, level, target_type, full_coverage.
Create a new strategic city record associated with a sovereign country.
Inputs: name (required), country_id (required), themes, description.
Initiate a 2-Phase Map-Reduce synthesis report on a frozen cluster snapshot.
Inputs: prompt (required), cluster_snapshot_id (required).
Compute connected-components clustering and freeze it immediately into an immutable database snapshot.
Inputs: level (required), title (required), target_type (required), full_coverage.
Create a new continent record in the catalog.
Inputs: name (required), description.
Create a new sovereign country record associated with a continent.
Inputs: name (required), continent_id (required), themes, description.
Delete a city record.
Inputs: id (required).
Delete a synthesis report along with its intermediate summaries and sub-reports.
Inputs: id (required).
Delete a frozen cluster snapshot along with its cascaded cluster groups and synthesis reports.
Inputs: id (required).
Delete a continent and its cascaded countries and cities.
Inputs: id (required).
Delete a country and its cascaded strategic cities.
Inputs: id (required).
Find nearest geopolitical or urban counterparts to a specified country or city using 1024-dimensional pgvector cosine distance.
Inputs: id (required), entity_type (required), limit, country_id, +2 more.
Calculate 1024-dimensional vector embedding for a city record.
Inputs: id (required), sync.
Calculate 1024-dimensional vector embedding for a country using the configured embedding model.
Inputs: id (required), sync.
Initiate a 3-Phase Hierarchical Deep Synthesis monograph, reusing Phase 1 summaries from a completed parent report.
Inputs: report_id (required), batch_size.
Retrieve details of a strategic city including its structured themes and associated country/continent.
Inputs: id (required), include_embedding.
Retrieve details of a specific archetype cluster group with all member countries or cities.
Inputs: id (required), include_members.
Retrieve complete scholarly report content, progress percentage, markdown monograph, and intermediate summaries.
Inputs: id (required), include_summaries, include_sub_reports.
Retrieve details of a frozen cluster snapshot including member groups and generated reports.
Inputs: id (required), include_groups, include_members, include_reports.
Retrieve details of a single continent including its sovereign countries.
Inputs: id (required), include_countries.
Retrieve full profile of a sovereign country including continent, thematic statecraft tags, and strategic cities.
Inputs: id (required), include_cities, include_embedding.
Check the status, progress, and result of an ActiveJob/Sidekiq background task.
Inputs: job_id (required).
Retrieve the raw OpenAPI 3.1 specification for the Statesman API.
Inputs: no named parameters.
Get overall platform health, catalog entity counts, embedding coverage stats, and active LLM configuration.
Inputs: no named parameters.
Retrieve a single Phase 2 batch analysis.
Inputs: id (required).
Retrieve a single Phase 1 per-cluster scholarly summary.
Inputs: id (required).
Get embedding completion metrics for Countries and Cities, active embedding/LLM parameters, and context window presets.
Inputs: no named parameters.
List and filter strategic urban power centers with civic/economic themes and embedding metadata.
Inputs: q, limit, theme, offset, +4 more.
List all archetype cluster groups belonging to a specific frozen snapshot.
Inputs: cluster_snapshot_id (required), include_members.
List generated multi-phase comparative geopolitics and urban power synthesis reports.
Inputs: limit, offset, status, is_detailed, +2 more.
List frozen archetype cluster snapshots.
Inputs: limit, offset, target_type, include_groups.
List world continents registered in Statesman with sovereign country counts.
Inputs: q, limit, offset, include_countries.
List and filter sovereign countries with statecraft themes, city counts, and vector embedding status.
Inputs: q, limit, theme, offset, +5 more.
List recent asynchronous background jobs (embedding calculations, LLM discoveries, synthesis reports).
Inputs: limit.
List all Phase 2 intermediate batch analyses belonging to a detailed synthesis report.
Inputs: cluster_report_id (required).
List all Phase 1 per-cluster analyses belonging to a synthesis report.
Inputs: cluster_report_id (required).
Trigger bulk LLM city discovery across all countries or a single country.
Inputs: sync, country_id.
Discover and populate sovereign countries for a specific continent via LLM generation.
Inputs: id (required), sync.
Trigger LLM discovery to populate all 7 standard continents with geopolitical descriptions.
Inputs: sync.
Trigger bulk LLM country discovery across all continents or a single continent.
Inputs: sync, continent_id.
Discover and generate 8-10 strategic cities for a country via LLM extraction.
Inputs: id (required), sync.
Unified cross-catalog semantic or keyword search across sovereign countries and strategic cities in the Statesman comparative geopolitics manifold.
Inputs: q (required), mode, limit, target_type.
Enqueue bulk embedding generation for all Countries or Cities.
Inputs: model_type (required), only_missing.
Update an existing city's attributes, country, or thematic tags.
Inputs: id (required), name, themes, country_id, +1 more.
Dynamically update the active LLM context window token size.
Inputs: context_window (required).
Update an existing continent's name or description.
Inputs: id (required), name, description.
Update an existing country's attributes, continent, or thematic tags.
Inputs: id (required), name, themes, description, +1 more.
Batch insert or update strategic cities scoped to a specific country.
Inputs: cities (required), country_id (required).
Batch insert or update continents matching case-insensitively on name.
Inputs: continents (required).
Batch insert or update sovereign countries scoped to a specific continent.
Inputs: countries (required), continent_id (required).
Poll a background job until completion or failure with configurable timeout.
Inputs: job_id (required), timeout_ms, poll_interval_ms.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 51 tools
Most tools map to distinct resources and actions, but several clusters overlap: populate_* versus bulk discovery versus batch upserts, and compute_clusters versus create_cluster_snapshot versus cluster reports. search and find_counterparts are also adjacent enough to require careful selection. Descriptions help, but the tool surface has multiple blurry boundaries.
The set is overwhelmingly consistent snake_case with verb_noun or verb_noun_qualifier patterns such as list_countries, create_city, and delete_cluster_snapshot. Minor deviations exist in the bare 'search' tool and compound names like generate_deep_synthesis, but the convention is still highly readable.
At 51 tools, the server is heavily over-scoped relative to a comparative geopolitics catalog. Many operations could be consolidated into generic entity CRUD, batch, embedding, synthesis, and job-management tools rather than exposing separate tools for every phase and sub-report type.
The surface covers the full lifecycle for continents, countries, cities, cluster snapshots, cluster groups, reports, summaries, jobs, settings, and embeddings. It includes create/read/update/delete, batch upserts, vector generation, synthesis workflows, polling, and platform introspection, so no obvious operational gap remains.
Agent-native MCP over US public + government records, entity- and parcel-keyed.
Private, multimodal knowledge store for agents: hybrid search with cited, provenance-backed results.
Mobility, geocoding and nearby urban services for AI agents.
Urban intelligence knowledge graph. Structured locality data for civic problem-solving.
