Stream an LLM chat turn that uses the MCP server as its toolbelt

SSE stream of one chat turn.

The LLM (Claude) sees every tool registered on our MCP server. When the model wants a tool, we dispatch it via mcp.call_tool — same code path as remote MCP clients hitting /mcp/ — and feed the result back. end_user_id (optional) pins all end-user-scoped tool calls to that contact.

The endpoint streams an event-stream of:

text_delta — incremental assistant text (append to the bubble).
tool_call — model decided to call a tool (name, input).
tool_result — JSON-string result (or error).
turn_end — one Claude turn finished (may loop again for tools).
done — full turn complete.
error — fatal; stream closes.

No RBAC dependency on this endpoint itself — tools enforce their own permissions via the @cx_tool registry, so a viewer-role caller chatting here can only invoke the read tools.

POST

mcp-chat

stream

Stream an LLM chat turn that uses the MCP server as its toolbelt

curl --request POST \
  --url https://api-sandbox.featherhq.com/v1/mcp-chat/stream \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "messages": [
    {
      "content": "<string>"
    }
  ],
  "end_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "model": "gpt-5.4-mini",
  "max_tokens": 4096
}
'

import requests

url = "https://api-sandbox.featherhq.com/v1/mcp-chat/stream"

payload = {
    "messages": [{ "content": "<string>" }],
    "end_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "model": "gpt-5.4-mini",
    "max_tokens": 4096
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    messages: [{content: '<string>'}],
    end_user_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    model: 'gpt-5.4-mini',
    max_tokens: 4096
  })
};

fetch('https://api-sandbox.featherhq.com/v1/mcp-chat/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.featherhq.com/v1/mcp-chat/stream",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'messages' => [
        [
                'content' => '<string>'
        ]
    ],
    'end_user_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'model' => 'gpt-5.4-mini',
    'max_tokens' => 4096
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.featherhq.com/v1/mcp-chat/stream"

	payload := strings.NewReader("{\n  \"messages\": [\n    {\n      \"content\": \"<string>\"\n    }\n  ],\n  \"end_user_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"model\": \"gpt-5.4-mini\",\n  \"max_tokens\": 4096\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.featherhq.com/v1/mcp-chat/stream")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"messages\": [\n    {\n      \"content\": \"<string>\"\n    }\n  ],\n  \"end_user_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"model\": \"gpt-5.4-mini\",\n  \"max_tokens\": 4096\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.featherhq.com/v1/mcp-chat/stream")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messages\": [\n    {\n      \"content\": \"<string>\"\n    }\n  ],\n  \"end_user_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"model\": \"gpt-5.4-mini\",\n  \"max_tokens\": 4096\n}"

response = http.request(request)
puts response.read_body

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

x-api-key

string

header

required

Body

application/json

Body for POST /v1/mcp-chat/stream.

messages is the full rolling history. end_user_id (optional) pins the bound end-user for the MCP tool calls — same semantics as the x-end-user-id header on the MCP HTTP endpoint.

messages

ChatMessage · object[]

required

Minimum array length: 1

Show child attributes

end_user_id

string<uuid> | null

model

string

default:gpt-5.4-mini

Chat completions model identifier (OpenAI).

max_tokens

integer

default:4096

Required range: 1 <= x <= 16384

Response

Successful Response

Stream an LLM chat turn that uses the MCP server as its toolbelt

curl --request POST \
  --url https://api-sandbox.featherhq.com/v1/mcp-chat/stream \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "messages": [
    {
      "content": "<string>"
    }
  ],
  "end_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "model": "gpt-5.4-mini",
  "max_tokens": 4096
}
'

import requests

url = "https://api-sandbox.featherhq.com/v1/mcp-chat/stream"

payload = {
    "messages": [{ "content": "<string>" }],
    "end_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "model": "gpt-5.4-mini",
    "max_tokens": 4096
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    messages: [{content: '<string>'}],
    end_user_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    model: 'gpt-5.4-mini',
    max_tokens: 4096
  })
};

fetch('https://api-sandbox.featherhq.com/v1/mcp-chat/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.featherhq.com/v1/mcp-chat/stream",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'messages' => [
        [
                'content' => '<string>'
        ]
    ],
    'end_user_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'model' => 'gpt-5.4-mini',
    'max_tokens' => 4096
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.featherhq.com/v1/mcp-chat/stream"

	payload := strings.NewReader("{\n  \"messages\": [\n    {\n      \"content\": \"<string>\"\n    }\n  ],\n  \"end_user_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"model\": \"gpt-5.4-mini\",\n  \"max_tokens\": 4096\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.featherhq.com/v1/mcp-chat/stream")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"messages\": [\n    {\n      \"content\": \"<string>\"\n    }\n  ],\n  \"end_user_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"model\": \"gpt-5.4-mini\",\n  \"max_tokens\": 4096\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.featherhq.com/v1/mcp-chat/stream")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messages\": [\n    {\n      \"content\": \"<string>\"\n    }\n  ],\n  \"end_user_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"model\": \"gpt-5.4-mini\",\n  \"max_tokens\": 4096\n}"

response = http.request(request)
puts response.read_body

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}