Developer & AI Integration

Connect FTIR.fun to Any AI Tool or App

Give your AI assistant or your own code direct access to 130,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

Reviewed & listed on

A Anthropic MCP Registry ✓ S Smithery ✓ M MCP.so ✓ Py PyPI ✓ n8n npm ✓

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 do not paste a personal key. Getting a personal key takes about a minute:

Sign in to FTIR.fun Create a free account if you do not have one. New accounts include free trial credits.
Open the API Keys dashboard Go to Account → API Keys and click Generate.
Copy and save the key immediately The full key (it starts with ftir_) is shown only once. Store it somewhere safe. If you lose it, just generate a new one.

🔑 Ready? Open the API Keys Dashboard in a new tab, then come back and follow the path you chose above.

⚠️ The hosted MCP server accepts only an account API key generated in the FTIR.fun API Keys Dashboard (starts with ftir_). Server-side master keys are for REST operators and cannot sign in to hosted MCP.

Step 1 — Which connection is right for you?

All three connect to the same engine: 130,000+ spectra, knowledge-graph reasoning, and literature citations. You only need one. Pick by how you work — not sure? MCP is the most popular choice for anyone using an AI assistant.

MCPPath A — MCP Server

MCP (Model Context Protocol) is the standard way for AI assistants to call outside tools. FTIR.fun runs a hosted MCP server — you do not install or run anything locally. You add one small config to your AI client, enter your API key, and your assistant gains seven FTIR tools.

✓ How sign-in works (read this first): FTIR.fun authenticates with the API key from your account, sent as an Authorization: Bearer header. There is no OAuth browser sign-in and no separate authorization page. If a client ever tries to open an authorization webpage, it is using an outdated config — see Troubleshooting below.

Pick your client for exact steps:

Set up FTIR.fun MCP in VS Code

Requires a current VS Code with GitHub Copilot Chat in Agent mode.

Open your project, then create the file .vscode/mcp.json Inside your project folder, make a folder named .vscode (if it does not exist) and a file named mcp.json inside it. Want FTIR.fun available in every project? Put the same JSON in your user-level settings: open the Command Palette, search 'Preferences: Open User Settings (JSON)', and add an mcp.servers entry there instead.

Paste this exact configuration Copy it as-is. Do not replace the ${input:...} part with your real key — VS Code will ask for the key securely when the server starts.

.vscode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "ftirfun-api-key",
      "description": "FTIR.fun API key",
      "password": true
    }
  ],
  "servers": {
    "ftirfun": {
      "type": "http",
      "url": "https://ftir.fun/mcp",
      "headers": {
        "Authorization": "Bearer ${input:ftirfun-api-key}"
      }
    }
  }
}

Start the ftirfun server Open the Command Palette, run “MCP: List Servers”, select ftirfun, and choose Start. Some VS Code versions show a Start action right above the server in mcp.json — that works too.
Paste only your API key when prompted When VS Code asks for ftirfun-api-key, paste just the raw key (starts with ftir_). Do not type the word Bearer — the config adds it automatically.
Confirm it connected Open Copilot Chat in Agent mode and check the tools list. FTIR.fun should show seven tools. Then try the test prompt below.
```
Use FTIR.fun to explain the FTIR peak at 1715 cm-1.
```

💬 Saw an authorization page or an “authorization page does not exist” error before? That was an outdated OAuth-style config. Delete the old ftirfun entry, paste the JSON above, reload VS Code, and start it again. Full fix in Troubleshooting.

Set up FTIR.fun MCP in Claude

Officially listed on the Anthropic MCP Registry. Works in Claude Desktop and Claude Code.

Open MCP server settings In Claude Desktop, go to Settings → Connectors → Add custom connector. In Claude Code, edit your MCP config file.
Add the remote server and Bearer header Use the hosted URL and add your API key as an Authorization header. Replace the placeholder with your real key (starts with ftir_).
Remote MCP server
```
URL: https://ftir.fun/mcp
Header: Authorization: Bearer ftir_your_key_here
```
Restart Claude and confirm Restart Claude Desktop, open the connectors/tools panel, and confirm FTIR.fun tools appear. Then ask a question in plain language.
```
Identify this polymer from its FTIR peaks: 2915, 1715, 1450 cm-1.
```

📎 Prefer Claude Code CLI? Run claude mcp add --transport http ftirfun https://ftir.fun/mcp --header "Authorization: Bearer ftir_your_key_here".

Set up FTIR.fun MCP in Cursor

Edit Cursor’s MCP config so your AI code editor can call FTIR.fun without leaving the IDE.

Open the MCP config file Create or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json inside your project.

Paste the server block Replace the placeholder with your real key (starts with ftir_).

~/.cursor/mcp.json

{
  "mcpServers": {
    "ftirfun": {
      "url": "https://ftir.fun/mcp",
      "headers": {
        "Authorization": "Bearer ftir_your_key_here"
      }
    }
  }
}

Reload Cursor and confirm Reopen Cursor, check Settings → MCP for the ftirfun server and its green status, then ask in chat.

Set up FTIR.fun MCP in Codex or any MCP harness

Works with OpenAI Codex and any MCP-compatible client that supports remote HTTP servers.

Add the server to your Codex config Point the client at the hosted URL and make sure it sends your API key as a Bearer header. Replace the placeholder with your real key.
~/.codex/config.toml
```
[mcp_servers.ftirfun]
url = "https://ftir.fun/mcp"
http_headers = { Authorization = "Bearer ftir_your_key_here" }
```
Restart and confirm the tools load Restart the client and confirm the seven FTIR.fun tools are listed before prompting.

Set up FTIR.fun MCP in Gemini CLI

Add FTIR.fun to an MCP-capable Gemini client using the same hosted URL and Bearer header.

Edit ~/.gemini/settings.json Add an httpUrl server entry with your API key header. Replace the placeholder with your real key.

~/.gemini/settings.json

{
  "mcpServers": {
    "ftirfun": {
      "httpUrl": "https://ftir.fun/mcp",
      "headers": {
        "Authorization": "Bearer ftir_your_key_here"
      }
    }
  }
}

Restart Gemini CLI and confirm Run /mcp to list servers and confirm ftirfun is connected before prompting.

🧩 Using another MCP client? Any client that supports a remote streamable-HTTP server works: set the URL to https://ftir.fun/mcp and send Authorization: Bearer <your key>. See the public server card for the full tool schema: server-card.json

✓ After a successful connection, your AI client should list these 7 tools: parse_ftir_spectrum, analyze_ftir_spectrum, submit_ftir_report, get_ftir_report_status, explain_peaks, find_spectra, fetch_result. If you see fewer tools or none at all, check Troubleshooting below.

APIPath B — REST API

Call FTIR.fun from your own code in any language — Python, JavaScript, R, MATLAB, Java, Go. Standard HTTP endpoints for identifying unknown spectra, explaining peaks, finding reference spectra, and fetching a past result by report number. Ideal for LIMS integrations, batch pipelines, or adding FTIR search to your own app.

Check that the REST service is online The health endpoint is public and does not consume points. It should return the JSON below. If you see an HTML page or a timeout, the service may be temporarily down.
curl
```
curl https://ftir.fun/health
```
Expected response
```
{"status":"ok","service":"ftirfun-api"}
```
Authenticate with the X-API-Key header Every protected endpoint takes your key in an X-API-Key header. The same account rules apply as in the web app: points, subscription, and rate limits. If the key is wrong or missing, you will get a 401 JSON error.
Auth header
```
X-API-Key: ftir_your_key_here
```

Make your first call — identify an unknown spectrum Send a peak list (or an uploaded file) and get ranked candidate materials with similarity scores and peak evidence. The options block is optional — defaults are top_k=15 (range 1–50) and tolerance_cm1=8 (range 1–30).

curl

curl -X POST https://ftir.fun/ftir/analyze_spectrum \
  -H "X-API-Key: ftir_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"spectrum":{"type":"ftir","x_unit":"cm-1","y_unit":"absorbance","peaks":[3026,1600,1493,1452,756,697]},"options":{"top_k":5,"tolerance_cm1":8}}'

Python

import requests

resp = requests.post(
    "https://ftir.fun/ftir/analyze_spectrum",
    headers={"X-API-Key": "ftir_your_key_here"},
    json={
        "spectrum": {"type": "ftir", "x_unit": "cm-1", "y_unit": "absorbance",
                     "peaks": [3026, 1600, 1493, 1452, 756, 697]},
        "options": {"top_k": 5, "tolerance_cm1": 8},
    },
)
print(resp.json())

Example success response (abbreviated)

{
  "success": true,
  "search_mode": "peak_only",
  "n_matches": 5,
  "confidence": 0.42,
  "confidence_source": "peak_match_score",
  "summary": "Peak-based FTIR matching ranks Styrene/acrylonitrile copolymer first...",
  "matches": [
    {"rank": 1, "name": "Styrene/acrylonitrile copolymer", "cas": "9003-54-7",
     "num": 119319, "score": 0.4214, "matched": 6}
  ],
  "evidence": ["3026 cm-1 -> alkyl C-H vibration (DOI 10.5650/jos.ess14201)"],
  "peak_explanations": [
    {"peak_cm1": 3026, "assignment": "alkyl C-H vibration",
     "evidence_type": "kg_peak_group"}
  ],
  "uncertainty": "The leading match is close to the runner-up..."
}

Explore the rest of the endpoints The full reference covers every endpoint, request and response formats, error codes, and more code samples. See the API Documentation.

What you want	Endpoint	Input
Identify an unknown spectrum	`POST /ftir/analyze_spectrum`	JSON body with spectrum.peaks or file_base64
Explain one or more peaks	`POST /ftir/explain_peak_assignments`	JSON body with peaks list or query text
Find a known reference spectrum	`POST /ftir/find_spectra`	JSON body with query string
Fetch a past result by report number	`GET /ftir/result/{result_num}`	Path parameter, optional ?language_code=en
Submit a full async report, then poll it	`POST /ftir/reports` · `GET /ftir/reports/{task_id}`	JSON body with file_base64 (required)
Parse an instrument file to peaks	`POST /parse-spectrum`	Multipart file upload OR JSON with file_base64

Key parameter reference

Parameter	Type	Default	Range	Used by
`top_k`	int	15	1–50	`analyze_spectrum`
`tolerance_cm1`	int	8	1–30	`analyze_spectrum`
`limit`	int	10	1–20	`find_spectra`
`sampling_mode`	string	(empty)	See list below	`reports`, `explain_peaks`
`language_code`	string	"en"	ISO 639-1	`reports`, `fetch_result`
`include_report`	bool	true	—	`get_ftir_report_status`

📘 Building a custom GPT or importing into another tool? Import our OpenAPI schema directly: openapi.platform.yaml.

Parse an instrument file (two ways)

The /parse-spectrum endpoint accepts either a multipart file upload or a JSON body with base64-encoded content. Both return the same response: detected peaks and the full curve.

Option A: multipart file upload

curl -X POST https://ftir.fun/parse-spectrum \
  -H "X-API-Key: ftir_your_key_here" \
  -F "file=@/path/to/sample.spc"

Option B: JSON with base64

curl -X POST https://ftir.fun/parse-spectrum \
  -H "X-API-Key: ftir_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"file_base64": "V2F2ZW51bWJlci...", "filename": "sample.spc"}'

Response

{
  "peaks": [697, 756, 1028, 1452, 1493, 1600, 3026],
  "spectrum": [{"x": 400.0, "y": 0.023}, {"x": 401.0, "y": 0.024}, ...],
  "status": "ok",
  "error": null
}

SkillPath C — Skills & Plugins

For popular AI and automation platforms we ship ready-made packages, so you do not have to write API calls by hand. Install a package or import a plugin, and FTIR.fun becomes a building block in your workflow. Each card below tells you exactly what to run or import.

LangChain

Python package · PyPI

Published

Drop-in tools for building FTIR-aware agents. Handles Base64 encoding, retries, and async calls for you.

Install

pip install langchain-ftirfun

Minimal call

from langchain_ftirfun import explain_peaks

result = explain_peaks(
    api_base_url="https://ftir.fun",
    api_key="ftir_your_key_here",
    peaks=[1715],
)
print(result)

Import FTIRFUN_TOOLS to get all seven functions in a list. Each function takes api_base_url and api_key as the first two arguments.

PyPI page

n8n

Community node · npm

Published

Drag-and-drop FTIR search into visual automation workflows. No coding — connect nodes and run.

Install

npm install n8n-nodes-ftirfun

Or add it in n8n: Settings → Community Nodes → Install.

npm page

Coze / Doubao

OpenAPI plugin · Publisher service key

Live

The Coze cloud plugin is published with three tools: spectrum analysis, reference library search, and peak explanation. End users can use it directly in Doubao without configuring any API key.

Endpoints

/coze/analyze_spectrum_flat
/coze/find_spectra
/coze/explain_peaks

Quota is tracked per user via Coze sys_uuid. The plugin uses a publisher-configured service key.

GPT

ChatGPT

Custom GPT · GPT Actions

Schema ready

Build a custom GPT that analyzes spectra, explains peaks, and finds reference spectra. Import our OpenAPI schema as an Action. Requires ChatGPT Plus.

Import URL

https://ftir.fun/openapi.platform.yaml

In the GPT editor: Configure → Actions → Import from URL. Set auth to API Key (header X-API-Key).

OpenAPI schema

Dify

Custom tool · OpenAPI

Schema ready

Add FTIR.fun as a custom tool in your Dify apps and agents by importing the same OpenAPI schema.

Import URL

https://ftir.fun/openapi.platform.yaml

In Dify: Tools → Create Custom Tool → import the schema, set the X-API-Key header.

Google Gemini API

Function declarations (SDK integration)

Ready

Use ready-made function declarations to call FTIR.fun from the Gemini API’s function-calling flow in your own code.

Declarations cover all seven operations, including parsing and asynchronous full reports.

Declaration JSON GitHub

What your AI can actually do

The current MCP, REST, n8n, and LangChain distributions expose seven operations. The published Coze plugin exposes three tools (analyze, find, explain), and other templates may expose a smaller declared set; check each platform card before use. 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.
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.

Supported files: SPA, SPC, OPUS, JCAMP-DX, CSV, TSV, Excel, JSON. 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. Keep the original file extension so FTIR.fun picks the correct parser.

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": "direct_read:spa",
     "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. Do not resubmit while a report is running — keep the task_id and poll it.

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"}

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, report_view (structured report content), 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..."}

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.

⚠️ Do not submit the same report again while it is queued or running. Keep the task_id and keep polling until it is complete or failed. Duplicate submissions 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 keep polling. Do not create duplicate report tasks.
`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.

View full API documentation → Custom integration? Contact us