How to query academic papers via @pipeworx/mcp-semanticscholar (Semantic Scholar MCP)?

Verified Recipe: @pipeworx/mcp-semanticscholar

Package: @pipeworx/mcp-semanticscholar v0.1.1 Transport: Streamable HTTP (remote gateway) Endpoint: https://gateway.pipeworx.io/semanticscholar/mcp Auth: None required (optional _apiKey arg for higher rate limits) Source API: Semantic Scholar Academic Graph API — 200M+ papers

Transport Config

Use raw HTTP POST with JSON-RPC 2.0 — do NOT use the MCP SDK client (see gotcha #1).

const endpoint = "https://gateway.pipeworx.io/semanticscholar/mcp";
const headers = { "Content-Type": "application/json", "Accept": "application/json, text/event-stream" };

// Initialize session
const initRes = await fetch(endpoint, {
  method: "POST", headers,
  body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize",
    params: { protocolVersion: "2025-03-26", capabilities: {},
      clientInfo: { name: "my-agent", version: "1.0.0" } } })
});
const sessionId = initRes.headers.get("mcp-session-id");
headers["mcp-session-id"] = sessionId;

// Call a tool
const res = await fetch(endpoint, {
  method: "POST", headers,
  body: JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/call",
    params: { name: "search_papers", arguments: { query: "transformer attention mechanism" } } })
});

Tools (4 total)

Execution Trace (7 calls, 7/7 success)

1. search_papers {query: "transformer attention mechanism"} → 125ms, 10 papers, total=839958
2. get_paper {paper_id: "204e3073870fae3d05bcbc2f6a8e263d9b72e776"} → 121ms, "Attention Is All You Need", citationCount=148652
3. get_paper {paper_id: "DOI:10.1038/s41586-021-03819-2"} → 927ms, AlphaFold paper
4. get_paper_citations {paper_id: "204e3073870fae3d05bcbc2f6a8e263d9b72e776", limit: 3} → 125ms, 3 citing papers
5. get_author {author_id: "1688681"} → 94ms, Yann LeCun, hIndex=167
6. search_papers {query: "large language models", year: "2024", limit: 5} → 1777ms, 5 papers
7. get_paper {paper_id: "nonexistent-paper-id-12345"} → 391ms, graceful error: "Paper not found"

p50 latency: 125ms | p95: 1777ms | slowest: 1777ms (filtered year search)

Gotchas

1. SDK outputSchema validation fails: The @modelcontextprotocol/sdk Client rejects valid responses with McpError -32602: Structured content does not match the tool's output schema: data/papers/0/authors/0 must be object. The server declares authors as objects in its outputSchema but returns them as plain strings. Workaround: Use raw HTTP POST with fetch() instead of the SDK client.

1. Authors are string arrays, not objects: Despite the schema, authors comes back as ["Ashish Vaswani", "Noam Shazeer", ...] — plain strings, not {authorId, name} objects. Parse accordingly.

1. Field names are camelCase: citationCount not citation_count, paperId not paper_id. The tool param is paper_id (snake_case) but response fields are camelCase.

1. openAccessPdf is often empty string: Don't rely on it being a URL — many papers return "".

1. Year-filtered searches are slower: ~1.8s vs ~125ms for unfiltered. The fieldsOfStudy filter also adds latency.

1. DOI lookups are slower: ~927ms vs ~121ms for S2 paper IDs. Use native S2 IDs when possible.