Headai MCP Server

Connect AI agents to decision intelligence — knowledge graphs, competitive analysis, trend signals, and recommendations from 150M+ data points.

24 Tools Read-only Safe Streamable HTTP OAuth 2.0 v1.2.0

Overview

Headai MCP Server is a Model Context Protocol server that connects AI agents — Claude, ChatGPT, GitHub Copilot, Cursor, or any MCP client — to Headai's Core Engine APIs. Build knowledge graphs from job ads, research articles, curricula, investment data, and more. Compare skills, detect trends, and get AI-powered career recommendations.

Server endpoints

POST/mcp — MCP protocol (JSON-RPC 2.0, Streamable HTTP)

GET/mcp — SSE stream for active sessions

DELETE/mcp — Session termination

GET/sse — Legacy SSE transport

POST/messages — Legacy SSE message endpoint

GET/health — Health check (JSON)

GET/tools — Tool listing (JSON)

Authentication

API key authentication

Every request requires a Headai API key. The server supports two auth modes:

Remote (OAuth 2.0): Connect via the hosted server at mcp.headai.dev. The OAuth flow prompts you to enter your API key during authorization.

Local (stdio): Set the HEADAI_API_KEY environment variable when running locally.

Contact headai.com for API key provisioning.

Setup

Claude Desktop / Claude Code (stdio)

{
  "mcpServers": {
    "headai": {
      "command": "node",
      "args": ["/path/to/headai-mcp-server/dist/index.js"],
      "env": {
        "HEADAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Remote server (Claude.ai, ChatGPT, Copilot)

MCP Server URL: https://mcp.headai.dev/mcp
Transport: Streamable HTTP
Auth: OAuth 2.0 (enter your API key during authorization)

Cursor / Windsurf

{
  "mcpServers": {
    "headai": {
      "url": "https://mcp.headai.dev/mcp",
      "transport": "streamable-http"
    }
  }
}

Tool reference

All 25 tools organized by category. Parameters marked required must be provided; others are optional with sensible defaults.

Core NLP Graph building Analysis & comparison Recommendations Graph operations Career intelligence Utility & admin Orchestration

Core NLP

headai_text_to_graphasync

Convert free-form text (CV, job description, article, course description) into a structured semantic knowledge graph using the v2 engine. Extracts skills, concepts, and relationships with optional plural grouping and semantic cleaning.

Endpoint: POST /v2/TextToGraph

Parameter	Type	Description
`text` required	string	Text to convert (min 10 chars)
`language`	string	ISO language code default: "en"
`ontology`	string	Ontology: headai, esco, yso, fibo default: "headai"
`legend`	string	Label for the resulting graph
`keyword_type`	string	"only_compounds" for compound words only
`group_plurals`	boolean	Collapse plural/singular variations into base form default: false
`enable_semantic_cleaning`	boolean	Group semantically similar words together default: false
`translate_to`	string	Translate output to another language (fi, sv, de, fr, es...)
`noise_list`	string	Comma-separated keywords to exclude
`use_stored_noise`	boolean	Use noise list stored for API key

headai_text_to_keywordsread-only

Extract weighted keywords and key concepts from text. Returns keywords with importance weights and quality indicators.

Endpoint: POST /TextToKeywords

Parameter	Type	Description
`text` required	string	Text to extract keywords from (min 10 chars)
`language`	string	ISO language code default: "en"
`ontology`	string	Ontology to use default: "headai"
`keyword_type`	string	"only_compounds" for compound words only
`noise_list`	string	Comma-separated keywords to exclude
`use_stored_noise`	boolean	Use stored noise list

Graph building

headai_build_knowledge_graph_v2asyncread-only

Preferred for all new builds. Faster engine with built-in quality processing: focused_build, plural grouping, semantic cleaning, and topic drift analysis. Two-step confirmation gate: first call returns preview + hash, second call with hash starts the build.

Endpoint: POST /v2/BuildKnowledgeGraph

Parameter	Type	Description
`dataset` required	string	Dataset: job_ads, investments, doaj, theseus, tiedejatutkimus, curriculum, news Note: v2 uses "investments" (not "investment_data") and "doaj" (not "doaj_articles")
`search_text` required	string	Comma-separated search terms. Commas = OR, hyphens = AND. Supports field scoping: school:SAMK, programme:ICT
`language`	string	Language code default: "en"
`ontology`	string	Ontology default: "headai"
`legend`	string	Graph label
`search_year`	string\|number	Year filter. Required for doaj, investments, news, tiedejatutkimus
`search_month`	string\|number	Month filter (0 = all)
`startDate` / `endDate`	string	Date range YYYY-MM-DD
`country`	string	Country code (e.g. "fi"). Mutually exclusive with city
`city`	string	City name or comma-separated list
`size`	number	Sample size 1-5000 default: 300
`focused_build`	boolean	Prune for strong triplets only default: true
`group_plurals`	boolean	Collapse singular/plural variants default: true
`enable_semantic_cleaning`	boolean	Cosine dedup on node embeddings default: true
`analyze`	boolean	Run Topic Drift Analysis default: false
`word_type`	string	"only_compounds" for multi-word terms
`noise_list`	string	Comma-separated exclusions
`update`	boolean	Force rebuild even if cached
`preview_hash`	string	Leave empty on first call. Provide hash from preview to start build

headai_scorecard_v2asyncread-only

Compare two knowledge graphs using the v2 engine with automatic semantic matching (cosine similarity). Collapses conceptually similar nodes, returns richer scoring (full_score, important_topics_score, data quality indicators), and persists results to a URL. Preferred for graph-vs-graph comparisons.

Endpoint: POST /v2/Scorecard

Parameter	Type	Description
`graph_1` required	string\|object	First knowledge graph (Goal) — URL string or JSON object
`graph_2` required	string\|object	Second knowledge graph (Document) — URL string or JSON object
`legend_1`	string	Display name for first graph default: "Goal"
`legend_2`	string	Display name for second graph default: "Document"
`limit`	integer	Min node weight for inclusion default: 1
`noise_list`	string	Comma-separated keywords to filter out
`enable_semantic_cleaning`	boolean	Collapse similar nodes via cosine similarity default: true
`update`	boolean	Force rebuild if cached default: false
`force_restart`	boolean	Force restart calculation default: false

headai_build_signalsasyncread-only

Analyze trends across 2+ chronological knowledge graph snapshots. Classifies skills into 8 signal groups: Emerging, Constantly Increasing, Increasing Last Period, Constant, Constant Last Period, Constantly Decreasing, Decreasing Last Period, Disappearing.

Endpoint: POST /BuildSignals

Parameter	Type	Description
`urls` required	string	Comma-separated graph URLs in ascending time order (min 2)
`map_legends` required	string	Comma-separated labels, one per URL. Must be years if predict=true
`predict`	boolean	Generate prediction for next period default: false
`dataset`	string	"doaj", "job_ads", or "custom" default: "custom"
`title`	string	Base title for the signal series

headai_run_analystadvanced

Advanced — prefer clean_graph and quality_check for common operations. Run a named analysis algorithm on knowledge graphs, scorecards, or signal results — hubs, cross-field bridges, gap analysis, quick wins, emerging and fading trends, undervalued niches, and quality scoring.

Parameter	Type	Description
`url` required	string	URL of the Headai graph to analyze
`report` required	integer	Algorithm code to run (e.g. 309 gap analysis, 1 hubs, 401 emerging trends).
`mode`	integer	Mode bitmask. Flags: 8=Finnish, 16=TOP10, 32=TOP20, 256=PLAIN, 512=JSON, 1024=TOP100 default: 1280

headai_visual_reportread-only

Extract structured data from a graph for visualization: companies (with counts), cities (with coordinates), skills (weights, degrees, groups), source documents, and statistics. No API call — fetches graph JSON directly.

Endpoint: Direct HTTP GET (no Megatron call)

Parameter	Type	Description
`graph_url` required	string	Graph JSON URL from a previous build
`title`	string	Report title (defaults to graph legend)

Recommendations

headai_compassread-only

Get personalized course or job recommendations based on a skill profile. Returns ranked recommendations with match scores, new skills gained, and details. Supports Zone of Proximal Development (ZPD) matching.

Endpoint: POST /Compass (timeout: 320s)

Parameter	Type	Description
`skills` required	string[]	User's current skills as concept strings (min 1)
`namespace` required	string	Target namespace (e.g. "metropolia", "TMT", "any", "kuntarekry")
`request`	string[]	Modes: "match", "zpd", "demand", "jobs", "companies", "curriculum", "researcher" default: ["match"]
`interests`	string[]	User's goal/interest skills
`language`	string	Language default: "en"
`completed`	string[]	Completed courses (course recs only)
`mandatory`	string[]	Mandatory courses
`country_limit`	string[]	ISO country codes for job search
`city_limit`	string[]	City names for job search

headai_get_jobs_by_textread-only

Search for real, current job listings matching skills or keywords. Returns job ads with title, company, URL, match score, matched skills, and missing skills.

Endpoint: POST /Utils (action: get_jobs_by_text)

Parameter	Type	Description
`search`	string	Free text search query
`keywords`	string	Comma-separated skill keywords
`area` required	string	City or region
`country` required	string	ISO 2-letter country code
`language` required	string	ISO 2-letter language code
`author`	string	Source: "mol" or "tmt"
`limit`	number	Max results 10-50 default: 20
`remove`	string	Keywords to exclude

Graph operations

headai_join_graphsread-only

Merge two or more knowledge graphs into a single combined graph.

Endpoint: POST /JoinKnowledgeGraphs

Parameter	Type	Description
`urls`	string	Comma-separated graph URLs (e.g. "url1,url2")
`graph_1` / `graph_2`	object	Graph JSON objects (alternative to urls)
`title`	string	Title for merged graph

headai_clean_graphcomposite

Remove noise and low-quality nodes from a knowledge graph. Native algorithm — no manual chaining needed.

Endpoint: Native algorithm + POST /ModifyKnowledgeGraph

Parameter	Type	Description
`graph_url` required	string	URL of the knowledge graph to clean
`aggressiveness`	string	"light" \| "normal" (default) \| "aggressive" — how much noise to remove

headai_quality_checkread-only

Structural quality score 0-100 with actionable recommendations for any knowledge graph.

Endpoint: Native algorithm (graph analysis)

Parameter	Type	Description
`graph_url` required	string	URL of the knowledge graph to assess

headai_modify_graphread-only

Filter and refine a knowledge graph by removing nodes, adjusting weights, or filtering by keywords.

Endpoint: POST /ModifyKnowledgeGraph

Parameter	Type	Description
`url` required	string	URL to the graph to modify
`keywords`	string	Comma-separated keywords to keep
`weight`	number	Minimum weight threshold (1-5)
`value`	number	Minimum value threshold
`max_nodes`	number	Maximum nodes to keep
`remove`	string	Comma-separated keywords to remove
`word_type`	string	"only_compounds" for multi-word terms
`title` / `legend`	string	New title or legend labels

headai_translate_graphread-only

Translate a knowledge graph between languages while preserving structure and relationships.

Endpoint: POST /TranslateKnowledgeGraph

Parameter	Type	Description
`url`	string	URL to the graph (provide url or data, not both)
`data`	object	Graph JSON object (alternative to url)
`language` required	string	Source language code
`translate_to` required	string	Target: BG, CS, DA, DE, EL, EN, ES, ET, FI, FR, HU, ID, IT, JA, LT, LV, NL, PL, PT, RO, RU, SK, SL, SV, TR, UK, ZH

Career intelligence

headai_digital_twinwrites data

Persistent, evolving skills profile stored on Headai. Operations: "add" (save graph as profile), "get" (retrieve stored profile), "share" (generate secure shareable URL).

Endpoint: POST /DigitalTwinStorage/AddToTwin (add) · GET /DigitalTwinStorage/GetTwin (get) · GET /DigitalTwinStorage/GetSecureShareLink (share)

Parameter	Type	Description
`operation` required	enum	"add", "get", or "share"
`twin_key` required	string	Unique twin identifier (e.g. "user_123")
`graph_url`	string	Graph URL to store (required for "add")

headai_skills_profilercompositewrites data

Builds an individual's Digital Twin from unstructured text (CV, portfolio, hobbies) and optional KOSKI data. Two-phase: preview extracted skills, then store after user review. Supports skill approval/rejection.

Chains: TextToGraph → JoinGraphs (optional) → ModifyGraph (optional) → DigitalTwin add

Parameter	Type	Description
`cv_text` required	string	CV / free text / portfolio (min 20 chars)
`user_key` required	string	Unique Digital Twin identifier
`koski_text`	string	Optional KOSKI transcript text
`language`	string	Language default: "en"
`legend`	string	Graph label
`preview_hash`	string	Hash from preview to confirm storage
`rejected_skills`	string	Comma-separated skills to remove
`approved_skills`	string	Comma-separated skills to keep (removes all others)

headai_career_navigatorcompositeread-only

Compares an individual's Digital Twin against a target (job market, free-text role, or employer profile). Produces gap analysis with training recommendations or job matches.

Chains: DigitalTwin get → BKG/TextToGraph (target) → Scorecard → Compass/Jobs

Parameter	Type	Description
`user_key` required	string	Digital Twin key for the user
`target_type` required	enum	"job_market", "text", or "twin"
`target_value` required	string	Search text (job_market), free text (text), or twin_key (twin)
`language`	string	Language default: "en"
`mode`	enum	"analyze", "training", "jobs", or "all" default: "analyze"
`namespaces`	string	Compass namespaces for training mode default: "Laurea,Stadin"
`area`	string	City for jobs mode
`country`	string	Country for jobs mode default: "fi"

headai_foresight_agentcompositeread-only

Produces an anonymised, aggregated skills picture of an organisation. The employer NEVER sees individuals. Hard-blocks if consenting participants < min_n (default 5) to prevent individual inference.

Chains: DigitalTwin get (per employee) → JoinGraphs → Scorecard (optional) → BuildSignals (optional)

Parameter	Type	Description
`employee_keys` required	string	Comma-separated Digital Twin keys for all employees
`excluded_keys`	string	Comma-separated opt-out twin_keys
`min_n`	number	Minimum consenting employees (hard block) default: 5
`employer_needs_text`	string	Free text describing employer skill needs for gap analysis
`language`	string	Language default: "en"
`include_signals`	boolean	Compute BuildSignals for trend overlay default: false
`include_quick_opportunities`	boolean	Run strategic gap analysis default: true

Utility & admin

headai_check_build_statusread-only

Poll async build status. Polls internally for up to 45 seconds and returns when ready. Call immediately after a build tool returns "building".

Parameter	Type	Description
`status_url` required	string	Status URL returned by the build tool
`graph_url`	string	Direct graph URL to check

headai_estimate_sizeread-only

Check data availability for a dataset before building. Only needed when the user specifically asks about data size.

Parameter	Type	Description
`dataset` required	string	Dataset name
`search_text`	string	Keywords to filter
`language`	string	Language default: "en"
`search_year`	string\|number	Year filter
`country` / `city`	string	Location filter

headai_fetch_graphread-only

Retrieve raw graph JSON by URL. Low-level debug tool.

Parameter	Type	Description
`url` required	string	Full URL to the graph JSON

headai_fetch_and_saveread-only

Fetch graph JSON and save to a local file. Returns compact summary + saved file path.

Parameter	Type	Description
`url` required	string	Full URL to the graph JSON
`save_path` required	string	Local file path (use /tmp/)

headai_list_token_endpointsread-only

List all API endpoints available for the current API key.

Endpoint: GET /Utils (action: get_token_endpoints)

No parameters.

headai_list_token_dataread-only

List all data built with your API key for a specific endpoint.

Endpoint: GET /Utils (action: get_token_data)

Parameter	Type	Description
`endpoint` required	string	Endpoint name: "BuildKnowledgeGraph", "Scorecard", "BuildSignals", etc.

Orchestration

headai_get_playbookread-only

Returns the full orchestrator playbook with tool-chaining logic, dataset rules, and workflow patterns. Call first at the start of each conversation.

No parameters. Returns static instructions.

Datasets

Knowledge graphs can be built from these real-world data sources:

Dataset	Content	Time horizon	Requires search_year
`job_ads`	Job postings from Finnish & EU job boards	Present / recent	No
`curriculum`	University curricula from 15+ Finnish institutions	Education	No
`theseus`	Finnish thesis repository	Education	No
`doaj_articles` / `doaj`	Open access academic journals (DOAJ)	5-10yr future	Yes
`investment_data` / `investments`	Startup / VC funding data	1-3yr future	Yes
`tiedejatutkimus`	Finnish research portal (research.fi)	Research	Yes
`news`	International news sources	Current	Yes

Note: v2 engine uses slightly different dataset names — "doaj" instead of "doaj_articles", "investments" instead of "investment_data".

Ontologies

Ontology	EN terms	FI terms	Notes
`headai`	168,833	51,432	Default. Best general-purpose
`esco`	136,175	36,287	EU standard skills taxonomy
`headai_optimized`	53,958	23,360	Compressed / faster variant
`lightcast`	—	—	Supports additional_data=true

Usage examples

1. Build a knowledge graph from job ads

"What AI skills are Finnish employers looking for?"

Tool: headai_build_knowledge_graph_v2
{
  "dataset": "job_ads",
  "search_text": "artificial-intelligence,machine-learning,deep-learning,neural-networks,NLP,computer-vision,data-science",
  "country": "fi",
  "language": "en",
  "size": 200
}

2. Compare curriculum vs. job market

"How well does our data science program match employer needs?"

Build two graphs, then use Scorecard:

Tool: headai_scorecard_v2
{
  "map_url_1": "https://megatron.headai.com/analysis/.../curriculum.json",
  "map_url_2": "https://megatron.headai.com/analysis/.../job_market.json",
  "legend_1": "Data Science Curriculum",
  "legend_2": "Employer Demand",
  "language": "en"
}

3. Detect trending skills over time

"How have cybersecurity skills evolved 2022-2025?"

Tool: headai_build_signals
{
  "urls": "https://.../cyber_2022.json,https://.../cyber_2023.json,https://.../cyber_2024.json,https://.../cyber_2025.json",
  "map_legends": "2022,2023,2024,2025",
  "predict": true
}

4. Get career recommendations

"I know Python, SQL, and pandas. What should I learn for data engineering?"

Tool: headai_compass
{
  "skills": ["python", "sql", "pandas", "data analysis", "statistics"],
  "interests": ["data engineering", "data pipelines", "cloud computing"],
  "namespace": "any",
  "request": ["match", "zpd"]
}

5. Cross-source horizon analysis

"What does the future look like for autonomous vehicles?"

Combine job_ads (now) → investment_data (1-3yr) → doaj_articles (5-10yr) into a signals analysis to see which skills are emerging across all horizons.

Troubleshooting

Empty results from BuildKnowledgeGraph

doaj_articles, investment_data, news, and tiedejatutkimus datasets require the search_year parameter. Without it, they return empty.

Compass timeout

Compass has a 320-second timeout due to intensive computation. Only 1 concurrent Compass request per API key (Megatron has 2 cores per key). The server sends progress heartbeats to keep the connection alive.

search_text formatting

Commas (,) mean OR — each term is searched independently. Hyphens (-) mean AND — both words must appear together. Use 5-20 domain-specific terms for best results. Example: "machine-learning,deep-learning,neural-networks,NLP,computer-vision"