AI generation API Claude Code: connect a local MCP wrapper safely

Published 2026-10-23

Claude Code can call a custom MCP server that wraps Genace’s REST API. The wrapper is code you operate, and the connection below is not a claim of an official Genace Claude Code plugin. Start from a local server exposing submit_image and inspect_job, then verify discovery before giving the assistant a generation task.

1. Prepare the server independently

Use the complete Python implementation in the MCP tool tutorial. Install its dependencies in a dedicated environment and record the absolute interpreter path. Set GENACE_API_KEY in the environment from which Claude Code will launch. Avoid passing a real credential as a literal command argument because shell history and process inspection can expose it.

For a POSIX development machine, the registration command can look like this after replacing both paths with your actual environment and file locations:

claude mcp add --transport stdio genace-local -- \
  /absolute/path/to/.venv/bin/python \
  /absolute/path/to/genace_mcp.py

claude mcp list

On Windows, use the absolute path to .venv/Scripts/python.exe and quote paths containing spaces. The -- separates Claude Code’s registration options from the command used to launch your server. Consult the installed CLI help and the linked official documentation if your version exposes different registration options.

2. Check connection without generating anything

Ask Claude Code to list the connected server’s tool names and explain their input schemas without invoking the submission tool. Verify it sees a prompt input for submission and a job ID input for inspection. The credential should appear in neither schema. If startup fails, first inspect interpreter paths, installed packages, and environment inheritance.

Use stderr for wrapper logging. A stdio MCP process uses stdout for protocol traffic, so a friendly startup print can break the connection before any API request happens. Keep diagnosis local until tool discovery works reliably.

3. Give one explicit generation instruction

Once the connection works, use an instruction with a clear scope, such as the following. This is an example prompt to review and adapt; it is not an instruction to submit a generation while reading this page.

Create one image of a red ceramic teapot on a linen table using submit_image.
Return and preserve the accepted job ID. Do not submit another image while
the first job is pending. Inspect that same job only when I request status.

The first tool returns an accepted job, not an image. Save the identifier in your operation record or project notes if you need recovery after the chat changes. A later request can call inspect_job using that exact identifier. The REST submission calls it job_id; the REST status response calls it id, and the wrapper normalizes that distinction for the client.

Common mistakes

Do not point an MCP URL configuration directly at /api/v1/images/generations. That endpoint accepts a REST generation request, not an MCP protocol session. Also do not let the assistant solve a pending render by invoking submission again. The POST route does not document request idempotency support, so repeated calls can create separate work.

A failed generation can be returned by a successful status HTTP request. Keep the state and error object in the tool response, and allow null outputs until success. Closing Claude Code or stopping its local MCP process does not automatically cancel a remote generation.

Verification checklist

Confirm tool discovery works before making a paid request.
Confirm the server inherits its key without exposing it in arguments.
Confirm one explicit user action creates one accepted job ID.
Confirm pending and failed fixtures do not cause automatic resubmission.

Use Claude Code’s MCP documentation for host configuration details and nonblocking generation design when extending the wrapper into a longer agent workflow.