Connecting other clients

Choose the right integration path for model clients, tools and agent execution.

Mellow can act as a local model endpoint and expose an allowed tool catalog to compatible clients. Start by deciding which direction the connection goes: an application calling Mellow, Mellow calling a model provider, or Mellow calling an external MCP service. These are different configurations.

Select the interface

Prepare the host

Start Mellow and load or select a model that the server can actually serve. Open the server controls and copy the displayed address and port. Prefer the loopback address for another application on the same Mac; network exposure is a separate choice.

Create the client credential through Mellow's access-key controls if authentication is required. Use a grant scoped to the intended agent where possible. Keep it in the client's secure settings or environment, not a public browser bundle.

Before configuring a large application, make a small request and inspect the result. A reachable server and a loaded model are separate prerequisites.

OpenAI-compatible requests

The server handles /v1/chat/completions and compatible model-list routes. Configure the client's base URL using the current server address plus the API prefix expected by that client. Some clients append /v1 themselves; avoid duplicating it.

A minimal request body has a model identifier and messages:

{
  "model": "MODEL_ID_FROM_THIS_SERVER",
  "messages": [
    {"role": "user", "content": "Reply with a short greeting."}
  ],
  "stream": false
}

Replace the placeholder with an identifier returned by this server. A provider's marketing name is not necessarily its API model identifier. Do not assume a model available in Mellow's interactive picker is exposed identically through every compatibility endpoint.

SDKs should receive the configured base URL and real credential through their normal client configuration. Streaming clients must parse the server's streaming format and handle cancellation and partial responses; concatenating arbitrary network chunks is not a complete stream parser.

Tools and MCP clients

External clients receive the tools allowed for their request context. Built-in host-only tool classes are hidden or rejected. The tool list in Mellow's own agent editor can therefore be larger than the list an external client sees.

The HTTP convenience routes include:

A call body follows the operation name and argument object returned by discovery:

{
  "name": "TOOL_NAME_FROM_DISCOVERY",
  "arguments": {}
}

These routes are Mellow's bridge interface. A client that expects an MCP transport must use the supported MCP connection mode rather than treating any JSON endpoint as a complete MCP server.

IDE and application setup

In an IDE's custom OpenAI-compatible provider form, enter Mellow's actual server address, model identifier, and credential. Test a plain text request before enabling agent tools or repository-wide context. Each IDE has its own support for streaming, tool calls, attachments, and reasoning fields.

For a web application, keep credentials on a trusted server component. A development browser can also encounter CORS restrictions even when a command-line request works. Configure allowed origins deliberately; do not expose a local control endpoint to arbitrary sites merely to suppress an error.

For a client on another machine, use the supported network or paired-device route. A public link is an address, not an authorization bypass or a promise that the client implements Mellow's peer protocol.

Diagnose before changing credentials

• Connection refused: check the running process, address, port, and listening mode.
• 401 or forbidden: inspect key scope, expiry, requested agent, and route policy.
• Model not found: refresh the host's model list and use the exact identifier.
• Tool absent: compare external tool exposure with the selected agent's capability settings.
• Browser-only failure: inspect CORS and mixed-content restrictions.
• Upgrade required: a protected remote agent route requires Secure Channel.
• Request hangs: inspect model loading, pending approval, and stream handling separately.

Continue with API reference, MCP services, and Identity.