MCP tools vs API endpoints for generation workflows

The short answer: tools describe actions; endpoints address HTTP operations

An MCP tool is a named, schema-described action that a client discovers from an MCP server and invokes through the protocol. A direct API endpoint is an HTTP address plus a method and request contract that application code calls explicitly. They are not rival names for the same wire operation. A tool can sit in front of one endpoint, combine several endpoints, poll an endpoint repeatedly, or perform work that has no HTTP backend at all.

For a generation workflow, choose MCP tools when a model-facing client should discover a bounded action such as generate or wait_generation from descriptions and JSON Schemas. Choose the direct API when your code should own URLs, HTTP methods, payload construction, status handling, retries, and orchestration. The same service can expose both: OfflineCreator's published MCP package registers model-facing tools, while its thin client translates those calls into the Studio /api/v1 routes.

MCP tool contract

Name, description, input schema, optional output schemaThe client discovers the available set and calls a selected name through MCP.

Direct API contract

HTTP method, route, headers, request body, responseApplication code selects the resource operation and handles the HTTP lifecycle.

Relationship

Adapter over the same generation serviceOne tool may map to one route, multiple routes, or repeated calls to one route.

Discovery changes who owns the integration details

With MCP, a client sends tools/list and receives the tools currently available to that authorized request. Each definition identifies the tool and its accepted input. The client then sends tools/call with a discovered name and matching arguments. The July 28, 2026 specification allows the list to vary with the authorization presented, so cached knowledge that a server once had a generation tool is not proof that the present caller can use it.

Streamable HTTP does not turn each tool into a separate REST-style URL. The official transport defines each MCP message as an HTTP POST to one MCP endpoint, and the tools specification places tools/call plus the selected tool name in the JSON-RPC message. Applied to the published OfflineCreator adapter, a generate call can arrive as POST /mcp carrying tools/call and name generate, after which the adapter sends POST /api/v1/generations to the Studio backend. The first route carries MCP; the second is the product API operation.

Discover

tools/listRead the authorized, schema-described registry instead of assuming tool names.

Invoke

tools/callSend the selected name and arguments through the MCP protocol.

Transport

POST to one Streamable HTTP MCP endpointDo not confuse the MCP transport URL with the backend API resource routes.

Concrete OfflineCreator tool-to-route map

The published @offlinecreator/mcp 0.1.1 package provides a concrete mapping. list_models reads GET /api/v1/models, and get_credits reads GET /api/v1/credits. generate starts work with POST /api/v1/generations. list_generations reads GET /api/v1/generations with a limit query, while get_generation reads GET /api/v1/generations/{generationId}. These are implementation facts for that package version, not routes required by MCP.

Several tool names deliberately reuse the same API operation. get_generation, wait_generation, and download_output all rely on GET /api/v1/generations/{generationId}: one returns current state, one polls until completion or failure, and one checks for a completed job before returning output-link fields. The model sees three task-oriented contracts, while the backend retains one status resource. That is the practical advantage of an adapter: tool granularity can match model decisions without forcing the HTTP API to duplicate resources.

list_models

GET /api/v1/modelsExpose model discovery as a named model-facing action.

generate

POST /api/v1/generationsTranslate a schema-checked tool call into the generation collection route.

get_generation, wait_generation, download_output

GET /api/v1/generations/{generationId}Use one status resource for immediate read, polling, and completed-output interpretation.

list_generations

GET /api/v1/generations?limit=...Represent a recent-jobs query as a bounded tool.

One tool can own a multi-route workflow

Image-to-video shows why a one-tool-to-one-endpoint assumption fails. In the published package, generate first reserves a generation through POST /api/v1/generations. When that response requires an upload, upload_input sends image bytes to POST /api/v1/generations/{generationId}/input and then submits the reserved job with POST /api/v1/generations/{generationId}/submit. If its wait option is set, the same tool handler continues polling the generation status route.

This composition is useful, but it also changes the failure surface. A direct API caller can checkpoint the reserve, upload, submit, and poll stages separately and apply route-specific retry or idempotency rules. An MCP caller receives the server's higher-level tool result and must preserve the returned generation identifier when making later calls. The current MCP guidance treats such an identifier as an explicit application handle, not hidden protocol session state. Losing it can break retrieval even though the underlying job still exists.

Reserve

generate → POST /api/v1/generationsRetain the returned generation identifier.

Attach and submit

upload_input → POST input, then POST submitOne tool handler coordinates two backend mutation routes.

Continue

Pass generationId explicitlyThe identifier is product state carried between calls, not an MCP session.

Continue with the boundary you need next

Read the end-to-end workflow when you need the larger path from client through generation state and output. Read the Streamable HTTP guide when the open question is how remote MCP messages reach one canonical endpoint. Return to the learning center for authorization, tools, resources, and operations. Those pages extend this comparison without replacing its tool-to-route map.

Evidence boundary

This comparison uses the July 28, 2026 MCP tools specification for discovery, invocation, authorization-sensitive registries, errors, and server controls. It uses the matching transport specification for the single-endpoint HTTP binding. The concrete OfflineCreator route map is limited to the publicly distributed @offlinecreator/mcp 0.1.1 package retrieved on August 8, 2026.

Those sources establish protocol requirements and a published adapter implementation. They do not establish that a deployed endpoint was reachable during this review, that every client interoperates with it, or that a generation completed through either interface. The mapping should therefore be read as version-bound contract evidence, not as an availability, performance, reliability, output-quality, or customer-outcome result.