Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to the OpenAlex MCP server

Vendor MCP
Open markdown

The OpenAlex MCP connector routes your AI agent's tool calls to OpenAlex's own MCP server through Scalekit. Each user signs in to OpenAlex once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 18 tools.

Tools
18
What they doRead · write · destructive
16 · 1 · 116 read1 write1 destructive
Users sign in with
OAuth app
Your own OpenAlex MCP server app

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>
  3. Create the OpenAlex MCP connection

    In AgentKit > Connections, create an OpenAlex MCP connection and copy its redirect URI. The name you give it is the connection_name your code passes. See Configure connections.

  4. Register an OAuth app

    OpenAlex MCP server connections use your own OAuth app. Register one with OpenAlex MCP server and add the redirect URI you copied.

    Then enter the app's Client ID and Client Secret on the OpenAlex MCP connection.

  5. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    const scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENVIRONMENT_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    const connector = 'openalexmcp'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize OpenAlex MCP:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'openalexmcp_analyze_works',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • openalexmcp_analyze_worksBuild a one-call profile of any set of works defined by a query and/or filters: an institution's output, a funder's portfolio, an author's career, a topic, a country, a journal.Read-only

    Analyze a set of works

    Build a one-call profile of any set of works defined by a query and/or filters: an institution's output, a funder's portfolio, an author's career, a topic, a country, a journal. Returns total works, open-access share by status, share of works in the top 10% and top 1% most-cited (field-normalized), counts by year and by type, and the top fields, topics, institutions, countries, sources, funders and authors, plus international and industry collaboration shares. Use it for research-office, library, and funder reporting questions ("summarize our 2024 research", "how much of NIH-funded work at UW is open access", "who does MIT collaborate with on AI"). Pick sections to keep the response small. Keyword queries only (no semantic mode). Each section costs one cheap API call.

    Inputs

    any_topic_idsarray
    OpenAlex topic IDs (OR): works that carry one of these among ANY of their topics, primary or not (typically ~3x as many works as topic_ids). OQL: `where topics is (T10102)`.
    author_idsarray
    OpenAlex author IDs (e.g. A5067184382). Resolve names with search_entities first.
    core_sources_onlyboolean
    Only works published in 'core' sources: reputable, well-indexed journals and repositories (see https://help.openalex.org/data/sources/). Useful to exclude low-quality venues.
    countriesarray
    ISO-3166 alpha-2 country codes of author institutions (OR), e.g. ["US","GB"]. Not supported with semantic search.
    from_yearinteger
    Earliest publication year, inclusive (e.g. 2020).
    funder_idsarray
    OpenAlex funder IDs (e.g. F4320332161).
    include_retractedboolean
    Include retracted works. Default false: retracted works are hidden and the response says so (retracted_works). Also honoured with oql, where the default leaves them out unless the query says otherwise (the echo then reads `it's not retracted`, or `non-retracted works` in the new form).
    institution_idsarray
    OpenAlex institution IDs (e.g. I27837315). Matches any author's affiliation.
    is_traditionalboolean
    true = only traditional scholarly works: the kinds the scholarly record has long counted (articles, books, chapters, theses, conference papers, preprints, reviews, editorials, letters...). false = only the rest (datasets, software, reports, abstracts, paratext...). Not the same as peer-reviewed: preprints and editorials are traditional.
    keyword_idsarray
    OpenAlex keyword ids (e.g. microplastics, human-health), any of them (OR). Find them with find_keywords. Keywords widen a text search; they do not replace it.
    languagestring
    ISO-639-1 language code, e.g. "en".
    min_citationsinteger
    Minimum cited_by_count. Not supported with semantic search.
    oa_statusarray
    Only these open-access statuses (OR).
    open_access_onlyboolean
    Only works with a free-to-read copy.
    publisher_idsarray
    OpenAlex publisher IDs (e.g. P4310319908).
    querystring
    Optional keyword search text (Boolean supported).
    raw_filterstring
    Escape hatch: extra OpenAlex filter expression appended verbatim, using the syntax documented at https://help.openalex.org/api/filtering/ (e.g. "has_abstract:true,primary_topic.field.id:17"). Combined with the structured filters above using AND.
    search_instring
    Where keyword/exact queries match. title_abstract_keywords (default, what openalex.org searches) matches title and abstract text, and also works tagged with a keyword that a phrase in the query names (catches other wordings, other languages and works with no abstract; every other word must still be in the text); title_and_abstract matches the text only; fulltext also matches the body text of ~100M works, plus keywords (broader, more noise; large reviews that merely mention a term will rank high); title matches titles only. Ignored for semantic mode.one of title_abstract_keywordstitle_and_abstractfulltexttitle
    sectionsarray
    Which sections to compute. Default: all.
    source_idsarray
    OpenAlex source (journal/repository) IDs (e.g. S137773608).
    to_yearinteger
    Latest publication year, inclusive.
    top_ninteger
    How many entries per top_* list. Default 10.
    topic_idsarray
    OpenAlex topic IDs (e.g. T10102), any of them (OR): works whose PRIMARY topic is one of these. Same meaning as OQL's `in the topic`, group_by topic and analyze_works top_topics. For works that carry the topic among any of their (up to 3) topics, use any_topic_ids.
    typesarray
    Only these work types (OR). Common: article, review, preprint, book-chapter, dataset.
  • openalexmcp_calculate_worksRun an OQL calculation and get the calculated groups: split a set of works by one to three fields, named values, searches, conditions or bins, and calculate count, mean/median/sum/min/max of a number, percent of a yes/no field, or each group's share.Read-only

    Calculate over works (OQL pipeline)

    Run an OQL calculation and get the calculated groups: split a set of works by one to three fields, named values, searches, conditions or bins, and calculate count, mean/median/sum/min/max of a number, percent of a yes/no field, or each group's share. Write it as a pipeline: get works where <conditions>; then, group those works by <field>; finally, summarize using <measures>. For one row per author, institution, source, publisher, funder, country or topic, start with them and say which works count, e.g. get authors at [University of British Columbia](I141945490) since 2022 who published works where title-abstract has kelp; then, summarize each author using count and mean FWCI (`at` reads the author's own record; `in [Asia](Q48)` for institutions; then, group each author's works by year for a further split). Or compare named things in one step, e.g. get works where topic is [CRISPR and Genetic Engineering](T10878); then, compare institution [Massachusetts Institute of Technology](I63966007) versus [Stanford University](I97018004) versus [Harvard University](I136199984) using count, mean FWCI, and percent open access. The full guide is the OQL reference in the server instructions (read_docs topic oql). Check a new query with check_oql first (free: limits with fixes, time estimate, price). Returns one row per group, keyed by the OQL words of each calculation (count, mean FWCI, ...), nested splits under groups, the summary (summary.all for the whole starting set; with two or more splits, summary.splits with each split's groups on their own, computed from the works: read these, never sum or average group rows), groups_count and next_page, the price, the canonical OQL and a reproduce_url. A query with no split or calculation gets then, summarize using count; a query that starts from authors, institutions, sources, topics, funders or publishers with no split lists them with their own fields. Retracted works are left out unless include_retracted=true or the query says otherwise.

    Inputs

    oqlstringrequired
    A pipeline OQL query, e.g. get works where country is [Kenya](KE) and published since 2015; then, group those works by year; finally, summarize using percent open access.
    include_retractedboolean
    Include retracted works. Default false.
    limitinteger
    Groups per page (the outer split), 1-200. Default 50. Groups come back by count.
    pageinteger
    Page of groups. Default 1.
    sortstring
    Order this page's rows by a calculated column, e.g. "mean FWCI" (descending). OQL itself has no sort; the API picks each page's groups by count.
  • openalexmcp_check_oqlFree check of any OQL query before running it, the calculation pipelines above all: whether it is valid, every problem with its fix (a parse error, a fourth split, too many groups, too slow), the time estimate against the ~10-second budget, the price in credits and USD, and the canonical text with each entity's name in brackets so you can confirm the IDs mean what you think.Read-only

    Check an OQL query (free)

    Free check of any OQL query before running it, the calculation pipelines above all: whether it is valid, every problem with its fix (a parse error, a fourth split, too many groups, too slow), the time estimate against the ~10-second budget, the price in credits and USD, and the canonical text with each entity's name in brackets so you can confirm the IDs mean what you think. The query is checked as calculate_works would run it (retracted works left out unless include_retracted=true). When it is not valid, apply the fix and check again.

    Inputs

    oqlstringrequired
    The OQL query to check.
    include_retractedboolean
    Check it with retracted works included. Default false, as the tools run it.
  • openalexmcp_find_candidate_worksWorks that are probably this author's but are not on their profile, from up to three sources: (1) name: the website's name ladder over raw bylines (as typed, reversed, initials, then looser word order) with a surname-plus-given-name gate, ranked by how much of the name the byline matches; (2) orcid: works carrying the ORCID in OpenAlex plus works listed on the public ORCID record (readable without login unless the author made them private); (3) siblings: other author profiles with the same name, with overlap signals, which may be duplicates of this person.Read-only

    Find works that may belong to an author

    Works that are probably this author's but are not on their profile, from up to three sources: (1) name: the website's name ladder over raw bylines (as typed, reversed, initials, then looser word order) with a surname-plus-given-name gate, ranked by how much of the name the byline matches; (2) orcid: works carrying the ORCID in OpenAlex plus works listed on the public ORCID record (readable without login unless the author made them private); (3) siblings: other author profiles with the same name, with overlap signals, which may be duplicates of this person. Every work reports this_authorship (the byline that would be attached, with affiliations and coauthors) so the user can be asked about anything unclear. Pass alternate names (from get_my_account, the profile, or a CV) one call at a time; for common names add institution, topic or year filters.

    Inputs

    author_idstringrequired
    The profile being curated (A…). Works already on it are excluded.
    any_topic_idsarray
    Narrow the name search to works that carry one of these topics (T…) among any of their topics, not only the primary one (a wide net for finding a person's works).
    from_yearinteger
    No description.
    institution_idsarray
    Narrow the name search to works with an author at these institutions (I…).
    limitinteger
    Max works per source. Default 25.
    namestring
    Name to search bylines for. Default: the profile's display name. Try each alternate name the person publishes under.
    orcidstring
    The author's ORCID, if they gave one.
    sourcesarray
    Which sources to run. Default: all that apply.
    to_yearinteger
    No description.
  • openalexmcp_find_keywordsFind the OpenAlex keywords for a topic, the first step of a thorough (high-recall) search.Read-only

    Find keywords

    Find the OpenAlex keywords for a topic, the first step of a thorough (high-recall) search. OpenAlex tags works with keywords (e.g. microplastics, human-health, antimicrobial-resistance) that also catch works using other wordings, other languages, or no abstract at all. search_works and keyword_search already match the keywords that the search's own phrases name; use this to find keywords that mean a facet under other names. Give the topic as a sentence (description) and, for better coverage, each facet's main phrase and synonyms (phrases). Returns candidate keywords with a match score, how many works carry each, and their three most-cited titles, so you can keep the ones that mean each facet and drop the rest. Then pass them to keyword_search. Costs about $0.01 (one /text/keywords call) plus a few cheap lookups.

    Inputs

    descriptionstringrequired
    The topic in a sentence or short paragraph, e.g. "how microplastics affect human health". At least 20 characters to be matched as text.
    per_phraseinteger
    Keyword-name matches kept per phrase. Default 5.
    phrasesarray
    Short names to look up among keyword names: each facet's main phrase and a synonym or two, e.g. ["microplastics", "nanoplastics", "human health"].
  • openalexmcp_get_entityFetch the full profile of one non-work entity by OpenAlex ID, or by ORCID (authors), ROR (institutions), or ISSN (sources).Read-only

    Get author, institution, source, topic, funder or publisher

    Fetch the full profile of one non-work entity by OpenAlex ID, or by ORCID (authors), ROR (institutions), or ISSN (sources). Includes works and citation counts, h-index, works/citations by year, top topics, affiliation history (authors), and identifiers.

    Inputs

    entity_typestringrequired
    Which kind of entity the ID refers to.one of authorsinstitutionssourcestopicsfunderspublishers
    idstringrequired
    OpenAlex ID (A5067184382, I27837315, S137773608, T10102, F…, P…), ORCID, ROR, or ISSN.
  • openalexmcp_get_my_accountWho is connected: name, email addresses (and which are verified), which API key this connection spends (personal or organization), the author profile this account has claimed (with a compact summary: names, institutions, topics, works count), the claim's status, and claim_eligibility: "instant" means a claim from this account is approved immediately (a verified academic, institutional or government email), "review" means the claim needs ORCID sign-in or a link to one of the user's papers on the profile that lists the account email (checked automatically within minutes; a web page alone never passes).Read-only

    Get my OpenAlex account

    Who is connected: name, email addresses (and which are verified), which API key this connection spends (personal or organization), the author profile this account has claimed (with a compact summary: names, institutions, topics, works count), the claim's status, and claim_eligibility: "instant" means a claim from this account is approved immediately (a verified academic, institutional or government email), "review" means the claim needs ORCID sign-in or a link to one of the user's papers on the profile that lists the account email (checked automatically within minutes; a web page alone never passes). Call this first for anything about the user's own profile.

    Inputs

    This tool takes no inputs.

  • openalexmcp_get_workFetch the full record for one scholarly work by OpenAlex ID (W2741809807), DOI (10.7717/peerj.4375 or a doi.org URL), arXiv id (2305.18290, arXiv:2305.18290v2 or an arxiv.org URL), PMID, or PMCID.Read-only

    Get work

    Fetch the full record for one scholarly work by OpenAlex ID (W2741809807), DOI (10.7717/peerj.4375 or a doi.org URL), arXiv id (2305.18290, arXiv:2305.18290v2 or an arxiv.org URL), PMID, or PMCID. Returns the authors with affiliations and ORCIDs (all of them up to 100; a bigger collaboration lists the first 100, the last and the corresponding authors, numbered, with authors_total), the full abstract, venue, open-access links, topics, keywords, funding, citations in every year the API counts, and related works.

    Inputs

    idstringrequired
    OpenAlex work ID, DOI, arXiv id, PMID, or PMCID.