NexusAPI MCP server, Python, Node.js and n8n examples

An open-source MCP server and production-minded examples for the asynchronous NexusAPI generation flow.

MCP tools for AI agents

The stdio server exposes four tools:

• nexusapi_list_models — search the live public model catalog;
• nexusapi_get_model_schema — inspect the live OpenAPI fields for one model;
• nexusapi_generate — create an asynchronous, potentially billable generation task;
• nexusapi_get_task — retrieve task status, result or error.

The server does not hide model-specific validation. Agents should inspect the live schema and obtain user approval before calling the billable generation tool.

After this repository is published, use it from a compatible local MCP host with:

{
  "mcpServers": {
    "nexusapi": {
      "command": "npx",
      "args": ["-y", "github:mat12121212/nexusapi-examples"],
      "env": {
        "NEXUS_API_KEY": "replace-me"
      }
    }
  }
}

Requirements: Node.js 20+ and an existing NexusAPI key. The key remains in the local host environment; do not commit it to the repository.

The repository demonstrates one lifecycle shared by the model schemas published in the live NexusAPI OpenAPI document:

1. Send POST /generate with a params object.
2. Store the returned task_id.
3. Poll GET /tasks/{task_id} with bounded exponential backoff.
4. Stop on completed or failed.

The model-specific fields still come from the live schema. Do not copy parameters between models without checking the NexusAPI documentation and OpenAPI JSON.

Examples

• src/mcp-server.mjs — local MCP server over stdio.
• python/nexusapi_client.py — reusable synchronous Python client.
• python/kling_video.py — Kling 3 text-to-video request.
• node/nexusapi-client.mjs — dependency-free Node.js 18+ client.
• node/gpt-image.mjs — GPT Image request.
• n8n/nexusapi-generate-and-wait.json — importable workflow with polling and failure handling.

Quick start: Python

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export NEXUS_API_KEY="replace-me"
python python/kling_video.py

Quick start: Node.js

export NEXUS_API_KEY="replace-me"
node node/gpt-image.mjs

n8n

Import the JSON file from n8n/, then create the NEXUS_API_KEY environment variable in the n8n runtime. Review the model parameters before executing the workflow. A successful run can incur generation charges.

Safety notes

• Keep the API key on the server. Never ship it in browser JavaScript.
• A client timeout does not prove that a generation stopped. Save task_id and check it again.
• Do not retry an ambiguous POST /generate automatically: the first request may have created a paid task.
• Treat 422 as a request/schema problem. Change the request before retrying.
• Respect 429 and temporary 5xx responses with bounded backoff.
• Review every agent-proposed generation before allowing the billable MCP tool call.

Verification

Verified against the live NexusAPI OpenAPI document and the official MCP TypeScript SDK v2 on 2026-08-01. The included smoke test performs the MCP initialize handshake, lists tools and calls all four tools against a local mock API. No paid generation is used by the test.

Disclosure

This repository is maintained for NexusAPI. The examples are open source under the MIT License; use of the API itself is governed by the service terms and pricing.