FTIR.funFTIR.fun
Developer & AI Integration

Connect FTIR.fun to Any AI Tool or App

Give your AI assistant or your own code direct access to 320,000+ reference spectra, knowledge-graph peak reasoning, and literature-backed interpretation. Choose one of three ways to connect — MCP for AI assistants, the REST API for code, or a ready-made Skill for no-code platforms. Every path below has step-by-step instructions written for first-time users.

1. Choose your path 2. MCP setup 3. REST API 4. Skills & plugins 5. What your AI can do 6. Troubleshooting
Listed on

Before you start — get your API key

MCP and the REST API both use one FTIR.fun API key. Coze/Doubao uses a service key configured by the plugin publisher, so end users work through the plugin without pasting a personal key. Getting a personal key takes about a minute:

  1. Sign in to FTIR.fun Create a free account (new accounts include free trial credits).
  2. Open the API Keys dashboard Go to Account → API Keys and click Generate.
  3. View or copy your API key The full key (it starts with ftir_) remains available in the API Keys dashboard. You can return there to view, copy, or revoke it.
🔑 Ready? Open the API Keys Dashboard in a new tab, then come back and follow the path you chose above.

Step 1 — Which connection is right for you?

All three connect to the same engine: 320,000+ spectra, knowledge-graph reasoning, and literature citations. You only need one. Pick the path that matches how you work; MCP is a convenient option for AI assistant users.

What your AI can actually do

The unified MCP and REST services expose the same FTIR.fun operation catalog. API keys may receive a smaller capability scope, while platform-specific declarations can intentionally publish only a subset. The operations below share the same FTIR.fun services.

Task MCP tool REST endpoint Say this to your AI
Read an instrument file parse_ftir_spectrum POST /parse-spectrum Parse sample.spc and list the detected peaks.
Convert native data and preserve metadata convert_native_spectrum POST /native-spectrum/convert Convert sample.spa to JDX and keep the source metadata.
Identify an unknown spectrum analyze_ftir_spectrum POST /ftir/analyze_spectrum Identify what polymer this spectrum is.
Submit a full tri-axis report submit_ftir_report POST /ftir/reports Submit sample.spa for a full report in ATR mode.
Poll and retrieve that report get_ftir_report_status GET /ftir/reports/{task_id} Check the report task and give me the link when done.
Explain peaks explain_peaks POST /ftir/explain_peak_assignments What do the peaks at 1715 and 1450 cm-1 indicate?
Find a known reference spectrum find_spectra POST /ftir/find_spectra Find reference spectra for polystyrene.
Reopen an earlier result fetch_result GET /ftir/result/{result_num} Fetch result 20260528100755416137536.
🎓 Academic Peak Assignment — For samples with a known composition, the advanced FTIR.fun REST/MCP capability assigns every measured peak with literature-tracked evidence. Each submission costs 30 points, or is free with an active subscription; status queries are not charged. Describe the task naturally (for example: “Assign all measured FTIR peaks for this spectrum; the sample is known PMMA; email the report to me”) — the client supplies the file and you never need to construct JSON or Base64 yourself. Completed results return both the JSON status and protected report addresses; reports are not exposed on a public download path.

Supported spectrum filename extensions (36): .spa, .spc, .sp, .abs, .irf, .irs, .dt, .jws, .jdx, .dx, .asc, .dpt, .opju, .opus, .ispd, .[0-9]+, .xlsx, .xls, .ods, .csv, .dat, .txt, .tsv, .json, .tab, .a2r, .asp, .spe, .map, .bsp, .spg, .srs, .smf, .ird, .fsm, .mat. Keep the original filename extension. Unsupported or unreadable files return supported_extensions and supported_formats. Valid sampling_mode values are KBr Pellet, Vapor, Solvent, Thin Film, Paraffin Mull, ATR, Diffuse Reflectance, Micro IR, and Others. Transmission is not a valid value.

find_spectra response example

find_spectra response 
{
  "success": true,
  "query": "polystyrene",
  "match_mode": "synonym",
  "match_count": 3,
  "summary": "Found 3 reference spectrum candidates for 'polystyrene'.",
  "results": [
    {"num": 555, "spectrum_number": 555, "name": "PS/PPO",
     "cas": "-", "source_type": "instrument_import",
     "peaks": [697, 756, 1028, ...], "x": [...], "y": [...]}
  ]
}

explain_peaks response example

explain_peaks response 
{
  "success": true,
  "search_mode": "peak_explanation",
  "peak_explanations": [
    {"peaks_cm1": [1715, 1450],
     "assignment": "1715 cm-1 suggests C=O stretching (ester or carboxylic acid)...",
     "evidence_type": "llm_general_knowledge"}
  ],
  "summary": "Peak explanation based on general FTIR knowledge..."
}

Getting the full report (async)

Quick screening (analyze_spectrum) returns immediately. The full tri-axis report runs in the background and typically takes 30–90 seconds. Keep the task_id and poll it rather than resubmitting.

  1. Submit Call submit_ftir_report (MCP) or POST /ftir/reports (REST). You get back a task_id and a reserved result_num. The file_base64 field is required; other fields (sampling_mode, prior_context, language_code, sample_name, sample_order_no) are optional.
    Submit example (REST) 
    curl -X POST https://ftir.fun/ftir/reports \
  -H "X-API-Key: ftir_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"file_base64": "V2F2ZW51bWJlci...", "filename": "sample.spa", "sampling_mode": "ATR", "language_code": "en"}'
    Submit response 
    {"success": true, "task_id": "rpt_abc123...", "result_num": "20260713...",
 "status": "queued", "status_url": "https://ftir.fun/ftir/reports/rpt_abc123..."}
  2. Poll Call get_ftir_report_status (MCP) or GET /ftir/reports/{task_id} every 5–10 seconds until completed is true. The completed response includes report_url, a report object (structured result content, with the detailed report_view inside it), and result_num.
    Poll example 
    curl https://ftir.fun/ftir/reports/rpt_abc123 \
  -H "X-API-Key: ftir_your_key_here"
    Poll response (in progress) 
    {"success": true, "task_id": "rpt_abc123", "status": "running", "progress": 45, "completed": false}
    Poll response (completed) 
    {"success": true, "task_id": "rpt_abc123", "status": "completed", "completed": true,
 "result_num": "20260713...", "report_url": "https://ftir.fun/outputdata/?num=20260713..."}
  3. Open the final report Open the full URL https://ftir.fun/outputdata/?num={result_num} in a browser to view the complete tri-axis result page rendered by FTIR.fun.
⚠️ Keep the task_id and poll until complete or failed. Duplicate submissions while queued or running waste points.

Troubleshooting

What you see What it means What to do
The client opens a browser authorization page, or says the authorization page does not exist. Your client is using an old OAuth-style server entry. FTIR.fun does not use OAuth — only an API key. Delete the old ftirfun server entry, paste the exact config from this page, reload the client, and start ftirfun again.
401 (MCP) / 401 invalid_api_key (REST) The API key is missing, expired, revoked, or pasted incorrectly. Restart the server and paste only the raw key (starts with ftir_). Generate a fresh key from the API Keys Dashboard if needed.
The server starts but no tools appear. The client has not refreshed its catalog, or the config uses the wrong key name. For VS Code, confirm mcp.json uses servers (not mcpServers). Then stop and start ftirfun, or reload the window.
403 insufficient_balance The account does not have enough points for that analysis. Check your balance or subscription in FTIR.fun, then retry.
429 rate_limit_exceeded REST analysis and parsing allow 60 requests per minute per API key; REST result and report-status reads use a separate 120 requests per minute bucket; MCP allows 60 calls per minute for each API key and tool. Wait for the retry period reported by the tool before calling again.
A report stays queued or running. Full reports run asynchronously and take longer than quick screening. Keep the same task_id and poll. If you lost the task_id, call GET /ftir/tasks to list your recent tasks and find it again.
422 or missing_input The request body is missing required fields or has invalid format. For analyze_spectrum, you must provide at least one of: peaks, query, or file_base64. Check that your JSON is valid, Content-Type is application/json, and required fields are present. See the example requests above.
413 file_too_large The uploaded spectrum file exceeds the size limit. Export a smaller file or use only peak positions via the spectrum.peaks field.

Ready to build?

The full REST reference has every endpoint, request and response formats, authentication, rate limits, error codes, MCP tool definitions, and code examples in Python and curl.

Submit Requirement Form