Updated docs

docs/apis/api-flow.md

@@ -210,6 +210,51 @@ Request schema:
 Response schema:
 `trustgraph.schema.FlowResponse`
 
+## Flow Service Methods
+
+Flow instances provide access to various TrustGraph services through flow-specific endpoints:
+
+### MCP Tool Service - Invoke MCP Tools
+
+The `mcp_tool` method allows invoking MCP (Model Control Protocol) tools within a flow context.
+
+Request:
+```json
+{
+    "name": "file-reader",
+    "parameters": {
+        "path": "/path/to/file.txt"
+    }
+}
+```
+
+Response:
+```json
+{
+    "object": {"content": "file contents here", "size": 1024}
+}
+```
+
+Or for text responses:
+```json
+{
+    "text": "plain text response"
+}
+```
+
+### Other Service Methods
+
+Flow instances also provide access to:
+- `text_completion` - LLM text completion
+- `agent` - Agent question answering
+- `graph_rag` - Graph-based RAG queries
+- `document_rag` - Document-based RAG queries
+- `embeddings` - Text embeddings
+- `prompt` - Prompt template processing
+- `triples_query` - Knowledge graph queries
+- `load_document` - Document loading
+- `load_text` - Text loading
+
 ## Python SDK
 
 The Python SDK provides convenient access to the Flow API:
@@ -233,6 +278,10 @@ flows = await client.list_flows()
 
 # Stop a flow instance
 await client.stop_flow("flow-123")
+
+# Use flow instance services
+flow = client.id("flow-123")
+result = await flow.mcp_tool("file-reader", {"path": "/path/to/file.txt"})
 ```
 
 ## Features

docs/apis/api-mcp-tool.md

@@ -0,0 +1,137 @@
+# TrustGraph MCP Tool API
+
+This is a higher-level interface to the MCP (Model Control Protocol) tool service. The input
+specifies an MCP tool by name and parameters to pass to the tool.
+
+## Request/response
+
+### Request
+
+The request contains the following fields:
+- `name`: The MCP tool name
+- `parameters`: A set of key/values describing the tool parameters
+
+### Response
+
+The response contains either of these fields:
+- `text`: A plain text response
+- `object`: A structured object response
+
+## REST service
+
+The REST service accepts `name` and `parameters` fields, with parameters
+encoded as a JSON object.
+
+e.g.
+
+In this example, the MCP tool takes parameters and returns a
+structured response in the `object` field.
+
+Request:
+```
+{
+    "name": "file-reader",
+    "parameters": {
+        "path": "/path/to/file.txt"
+    }
+}
+```
+
+Response:
+
+```
+{
+    "object": {"content": "file contents here", "size": 1024}
+}
+```
+
+## Websocket
+
+Requests have `name` and `parameters` fields.
+
+e.g.
+
+Request:
+
+```
+{
+    "id": "akshfkiehfkseffh-142",
+    "service": "mcp-tool",
+    "flow": "default",
+    "request": {
+        "name": "file-reader",
+        "parameters": {
+            "path": "/path/to/file.txt"
+        }
+    }
+}
+```
+
+Responses:
+
+```
+{
+    "id": "akshfkiehfkseffh-142",
+    "response": {
+        "object": {"content": "file contents here", "size": 1024}
+    },
+    "complete": true
+}
+```
+
+e.g.
+
+An example which returns plain text
+
+Request:
+
+```
+{
+    "id": "akshfkiehfkseffh-141",
+    "service": "mcp-tool",
+    "request": {
+        "name": "calculator",
+        "parameters": {
+            "expression": "2 + 2"
+        }
+    }
+}
+```
+
+Response:
+
+```
+{
+    "id": "akshfkiehfkseffh-141",
+    "response": {
+        "text": "4"
+    },
+    "complete": true
+}
+```
+
+
+## Pulsar
+
+The Pulsar schema for the MCP Tool API is defined in Python code here:
+
+https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/schema/mcp_tool.py
+
+Default request queue:
+`non-persistent://tg/request/mcp-tool`
+
+Default response queue:
+`non-persistent://tg/response/mcp-tool`
+
+Request schema:
+`trustgraph.schema.McpToolRequest`
+
+Response schema:
+`trustgraph.schema.McpToolResponse`
+
+## Pulsar Python client
+
+The client class is
+`trustgraph.clients.McpToolClient`
+
+https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/clients/mcp_tool_client.py