#Connect MCP clients

Choose two independent things: who calls the model, and how the client connects.

Both host and executor work over stdio or HTTP. Start with host below, then switch to a configured API if needed. Tool registration does not intercept every message.

#Standalone stdio

Complete installation. Codex registration is not required. Save intent.host.config.js in an ESM project, or use .mjs for a standalone file. Record its actual absolute path.

export default {
  mode: 'host',
  instances: {orders: {language: 'en', schema: {
    type: 'object',
    properties: {orderId: {type: 'string', description: 'An order ID explicitly supplied by the user; preserve leading zeros; applies only to order intents'}},
  }}},
};

This trusted Node.js module imports no packages and can be saved independently. Have your MCP client start:

intent-runtime-mcp --config /absolute/path/intent.host.config.js

Select STDIO in the client. Clients supporting mcpServers can use:

{
  "mcpServers": {
    "intent-runtime": {
      "command": "intent-runtime-mcp",
      "args": ["--config", "/absolute/path/intent.host.config.js"]
    }
  }
}

Replace the path. If the client PATH cannot find the command, use the executable's absolute path. On Windows use .cmd if supported; otherwise invoke node with the installed dist/cli/mcp.js absolute path. Codex users can use setup. stdout carries protocol only; inspect stderr for logs.

executor instances require a model executor; host does not. --help/--version are supported. Invalid arguments exit 2, loading/startup failures exit 1, normal EOF or SIGINT/SIGTERM exits 0. Keep stdout for MCP and logs on stderr.

#HTTP and a custom port

Reuse the same configuration:

intent-runtime-mcp --config /absolute/path/intent.host.config.js --transport http --host 127.0.0.1 --port 3001 --path /mcp

Expect Intent MCP listening at http://127.0.0.1:3001/mcp. Keep the process running and add a Streamable HTTP client connection:

{
  "mcpServers": {
    "intent-runtime": {
      "url": "http://127.0.0.1:3001/mcp"
    }
  }
}

If the client uses a form instead, enter the same URL. Three host tools should appear. If the port is occupied, choose another and update the client URL. Stop with Ctrl+C.

These HTTP options belong to process startup, not Intent configuration. stdio rejects them. HTTP uses stateful Streamable HTTP with protocols 2025-06-18 / 2025-11-25; stdio also supports 2026-07-28. The client must support the selected protocol.

Retain the negotiated Mcp-Session-Id; prepare and accept need the same logical session. HTTP allows at most 128 sessions, reclaims sessions after 30 minutes without new requests, and limits bodies to 4 MiB. This is not durable business conversation storage. Default binding is local. Configure authentication, HTTPS, and public access in your deployment layer; the command does not manage OAuth or proxies.

#Remote addresses and HTTPS proxies

--host binds the process; --public-origin identifies the origin the client actually accesses. They may differ. Binding 0.0.0.0 or :: requires a public origin; a wildcard bind address is not a client URL.

For a controlled LAN:

intent-runtime-mcp --config /absolute/path/intent.host.config.js --transport http --host 0.0.0.0 --port 3001 --public-origin http://192.168.1.10:3001

Replace the IP and connect to http://192.168.1.10:3001/mcp. This does not add encryption or authentication. Public deployment belongs behind configured TLS and access controls.

For https://mcp.example.com/mcp, with local process binding:

intent-runtime-mcp --config /absolute/path/intent.host.config.js --transport http --host 127.0.0.1 --port 3001 --public-origin https://mcp.example.com

This Nginx route belongs inside an existing TLS/access-controlled server block. Your deployment supplies certificates, authentication, and the domain:

location = /mcp {
    proxy_pass http://127.0.0.1:3001;
    proxy_http_version 1.1;
    proxy_set_header Host $http_host;
    proxy_buffering off;
    proxy_read_timeout 3600s;
}

Clients use https://mcp.example.com/mcp. Preserve public Host, original Origin, MCP session/protocol headers, and streaming responses. Nondefault ports must match in public-origin and Host. Arbitrary X-Forwarded-* headers do not expand trust; do not rewrite an invalid Origin to bypass checks. Public Host must match the configured origin's Host; supplied Origin must match scheme, host, and port. Local diagnostic addresses remain available.

Validate connection, tool discovery, and prepare/accept in one session. Mismatching Host/Origin should return 403. Request-boundary tests do not replace validation of your actual proxy, certificates, authentication, and client.

#Complete API-backed configuration

Use this instead of host configuration. Save in a project with Intent Runtime installed, set INTENT_API_KEY and INTENT_MODEL, and start with its absolute path. It selects no business fields by default.

import {createApiExecutor} from '@devcodex/intent-runtime/adapters/api';
const apiKey = process.env.INTENT_API_KEY, model = process.env.INTENT_MODEL;
if (!apiKey || !model) throw new Error('Set INTENT_API_KEY and INTENT_MODEL.');
export default {mode: 'executor', instances: {main: {language: 'en', executor: createApiExecutor({provider: 'openai', apiKey, model})}}};

#Complete the first recognition

In a tool-capable AI client, ask: “Use intent-runtime to recognize 'Look up order 000123. Do not cancel the order.' Extract the order ID, show the goal and prohibition, and do not perform order operations.”

Host mode lists intent_prepare, intent_accept, intent_cancel and needs the client model to complete the handoff. A client that only lists tools does not finish recognition. See Host handoff. Codex setup installs the corresponding Skill.

Executor mode can call:

{
  "name": "intent_parse",
  "arguments": {"input": "Look up order 000123. Do not cancel the order."}
}

Without a Schema, do not select business fields. structuredContent should preserve the lookup and prohibition; read the result. Host makes no additional API call; executor uses the configured model.

#Add tools to an existing service

Keep your SDK, transport, and tools; start with the four integration points. Existing HTTP services use the same adapter while retaining listener, authentication, and logical connections. Do not rebuild a host session for every HTTP request.

#Parameter and protocol reference

See Adapter API, tool input, envelopes, protocols, and complete replies.