@pyai/mcp 0.5.0 → 0.5.1

package/AGENT_GUIDE.md

@@ -84,3 +84,17 @@ limits. Authorized organization, project and key IDs remain in structured
 output; `whoami({"verbose":true})` also includes them in text. This reduces
 prompt clutter, not host access to identity metadata. Credential-shaped fields
 are omitted in both modes. Never paste keys or full identity dumps into reports.
+
+## Hosted connection boundaries
+
+The hosted OAuth MCP connection uses existing PyAI projects and owned phone numbers.
+Number purchasing is not exposed through hosted MCP. The REST API and local stdio
+integration retain their separate contracts. Hosted agent tool bindings accept
+saved tool IDs and enabled flags, not credentials or arbitrary connection settings.
+Configure those settings privately in the PyAI console. Retained bindings preserve
+their saved settings, and hosted agent responses omit connection configuration.
+
+Supply only audio and text you are authorized to process. Do not submit payment-card
+data, protected health information, government identifiers, passwords, or API keys.
+If an operation exceeds the project's entitlement, report the limitation without
+initiating a purchase or repeatedly resubmitting the request.

package/README.md

@@ -138,3 +138,17 @@ limits. Authorized organization, project and key IDs remain in structured
 output; `whoami({"verbose":true})` also includes them in text. This reduces
 prompt clutter, not host access to identity metadata. Credential-shaped fields
 are omitted in both modes. Never paste keys or full identity dumps into reports.
+
+## Hosted connection boundaries
+
+The hosted OAuth MCP connection uses existing PyAI projects and owned phone numbers.
+Number purchasing is not exposed through hosted MCP. The REST API and local stdio
+integration retain their separate contracts. Hosted agent tool bindings accept
+saved tool IDs and enabled flags, not credentials or arbitrary connection settings.
+Configure those settings privately in the PyAI console. Retained bindings preserve
+their saved settings, and hosted agent responses omit connection configuration.
+
+Supply only audio and text you are authorized to process. Do not submit payment-card
+data, protected health information, government identifiers, passwords, or API keys.
+If an operation exceeds the project's entitlement, report the limitation without
+initiating a purchase or repeatedly resubmitting the request.

package/dist/extra-tools.js

@@ -28,7 +28,7 @@ export const EXTRA_TOOLS = [
     },
     {
         name: "create_dub",
-        description: "Submit an audio URL for translation and dubbing. Consumes usage. Keep job_id and poll get_dub_job; do not submit again after a timeout.",
+        description: "Fetch audio from the user-authorized HTTPS source URL and start a translation and dubbing job. Accesses an external source and consumes usage. Keep job_id and poll get_dub_job; do not submit again after a timeout.",
         inputSchema: obj({
             source_url: { type: "string", format: "uri", pattern: "^https://" },
             source_lang: string("Source language from get_dub_capabilities."),
@@ -37,8 +37,8 @@ export const EXTRA_TOOLS = [
     },
     {
         name: "get_dub_job",
-        title: "Dubbing",
-        description: "Check a submitted Dub job. Poll pending/processing states without resubmitting.",
+        title: "Get dubbing job status",
+        description: "Retrieve the status and available results of an existing dubbing job by job_id. This read does not start or repeat a job. Poll pending/processing states without resubmitting.",
         inputSchema: obj(id, ["job_id"]),
     },
     {
@@ -88,7 +88,7 @@ export const EXTRA_TOOLS = [
             },
             language: {
                 type: "string",
-                enum: ["en", "es", "fr", "de", "hi", "it", "pt", "nl"],
+                enum: ["en", "es", "fr", "de", "hi", "it", "pt", "nl", "zh", "yue", "ar", "id", "ko", "th", "vi", "ja", "tr", "ms", "sv", "da", "fi", "pl", "cs", "fil", "fa", "el", "hu", "mk", "ro"],
             },
         }, ["audio_base64", "filename"]),
     },

package/dist/generated-tools.js

@@ -609,7 +609,7 @@ export const API_TOOLS = [
                                 "null"
                             ],
                             "maxLength": 200,
-                            "description": "TTS delivery direction for this managed Agent on instruct-capable voice tiers. Omit or set null for PyAI's natural conversational pace; an inline Omni `configure.voice_instruct` wins for that session."
+                            "description": "Stored delivery direction for instruct-capable voice tiers. Current Omni routes support neutral delivery only: omit or set null for neutral speech. A saved custom value is rejected when configuring Omni; an inline empty `configure.voice_instruct` resets it to neutral for that session."
                         },
                         "brain_model": {
                             "type": [
@@ -686,9 +686,20 @@ export const API_TOOLS = [
                                 "es",
                                 "de",
                                 "hi",
+                                "zh",
+                                "it",
+                                "pt",
+                                "ja",
+                                "ko",
                                 null
                             ],
-                            "description": "Requested language for this Agent's Omni sessions. `null` or absent means `en`. Availability is staged: as of 2026-08-13 public serving is `en`, `fr`, `es`, and `hi`; `de` falls back to English. Inspect the session's `configured.language_active` and `language_fallback` fields before assuming the requested language is active. See the Language support reference."
+                            "x-staged-language-ids": [
+                                "ht",
+                                "zh-CN",
+                                "ar-MSA",
+                                "ar-Gulf"
+                            ],
+                            "description": "Requested language for this Agent's Omni sessions. `null` or absent means `en`. Availability is staged: public serving includes `en`, `fr`, `es`, `hi`, `it`, `pt`, `ja`, and `ko`; `de` and the legacy `zh` alias fall back to English unless explicitly enabled with qualified endpoints. Canonical staged route identifiers are exposed in `x-staged-language-ids` for internal integration only and are rejected by the public control plane until qualified. Inspect the session's `configured.language_active` and `language_fallback` fields before assuming the requested language is active. See the Language support reference."
                         },
                         "metadata": {
                             "type": [
@@ -936,7 +947,7 @@ export const API_TOOLS = [
                                 "null"
                             ],
                             "maxLength": 200,
-                            "description": "TTS delivery direction for this managed Agent on instruct-capable voice tiers. Omit or set null for PyAI's natural conversational pace; an inline Omni `configure.voice_instruct` wins for that session."
+                            "description": "Stored delivery direction for instruct-capable voice tiers. Current Omni routes support neutral delivery only: omit or set null for neutral speech. A saved custom value is rejected when configuring Omni; an inline empty `configure.voice_instruct` resets it to neutral for that session."
                         },
                         "brain_model": {
                             "type": [
@@ -1013,9 +1024,20 @@ export const API_TOOLS = [
                                 "es",
                                 "de",
                                 "hi",
+                                "zh",
+                                "it",
+                                "pt",
+                                "ja",
+                                "ko",
                                 null
                             ],
-                            "description": "Requested language for this Agent's Omni sessions. `null` or absent means `en`. Availability is staged: as of 2026-08-13 public serving is `en`, `fr`, `es`, and `hi`; `de` falls back to English. Inspect the session's `configured.language_active` and `language_fallback` fields before assuming the requested language is active. See the Language support reference."
+                            "x-staged-language-ids": [
+                                "ht",
+                                "zh-CN",
+                                "ar-MSA",
+                                "ar-Gulf"
+                            ],
+                            "description": "Requested language for this Agent's Omni sessions. `null` or absent means `en`. Availability is staged: public serving includes `en`, `fr`, `es`, `hi`, `it`, `pt`, `ja`, and `ko`; `de` and the legacy `zh` alias fall back to English unless explicitly enabled with qualified endpoints. Canonical staged route identifiers are exposed in `x-staged-language-ids` for internal integration only and are rejected by the public control plane until qualified. Inspect the session's `configured.language_active` and `language_fallback` fields before assuming the requested language is active. See the Language support reference."
                         },
                         "metadata": {
                             "type": [

package/dist/hosted-policy.js

@@ -0,0 +1,33 @@
+// Remote conversational clients use saved connections, never credential inputs
+// or digital-service checkout. The REST API and local stdio retain their contract.
+export const HOSTED_EXCLUDED_TOOLS = new Set(["create_sandbox_key", "telephony_buy_number"]);
+export const AGENT_WRITE_TOOLS = new Set(["create_agent", "update_agent", "set_agent_tools"]);
+export function hostedTools(tools) {
+    return tools.filter(t => !HOSTED_EXCLUDED_TOOLS.has(t.name)).map(t => {
+        if (!AGENT_WRITE_TOOLS.has(t.name))
+            return t;
+        const schema = structuredClone(t.inputSchema);
+        const body = schema.properties.body;
+        body.additionalProperties = false;
+        const bindings = t.name === "set_agent_tools" ? body : body.properties.tools;
+        if (bindings?.items) {
+            bindings.items = {
+                type: "object", required: ["tool_id"], additionalProperties: false,
+                properties: {
+                    tool_id: { type: "string", description: "ID of an existing tool. Configure its connection privately in the PyAI console." },
+                    enabled: { type: "boolean", default: true },
+                },
+            };
+            bindings.description = "Replace bindings using saved tool IDs. Existing settings are preserved for retained bindings. Credentials and connection settings are not accepted through MCP.";
+        }
+        return { ...t, inputSchema: schema, description: t.description + " Use saved tool IDs; configure connection settings privately in the PyAI console. Never supply credentials." };
+    });
+}
+export function withoutBindingConfig(value) {
+    if (Array.isArray(value))
+        return value.map(withoutBindingConfig);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).filter(([key]) => key !== "config")
+        .map(([key, entry]) => [key, withoutBindingConfig(entry)]));
+}

package/dist/server.js

@@ -1,9 +1,11 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, McpError, ErrorCode, } from "@modelcontextprotocol/sdk/types.js";
-import { TOOLS, TOOL_SCOPES, callTool, localContext, } from "./tools.js";
-import { GUIDE, RESOURCES, SERVER_INSTRUCTIONS, WORKFLOWS, } from "./workflows.js";
-export const MCP_VERSION = "0.5.0";
+import { TOOLS, HOSTED_TOOLS, TOOL_SCOPES, callTool, localContext, } from "./tools.js";
+import { RESOURCES, workflowsForMode, guideForMode, instructionsForMode, } from "./workflows.js";
+export const MCP_VERSION = "0.5.1";
 export function createMcpServer(client, context = localContext) {
+    const tools = context.mode === "http" ? HOSTED_TOOLS : TOOLS;
+    const workflows = workflowsForMode(context.mode);
     const server = new Server({
         name: "pyai",
         version: MCP_VERSION,
@@ -11,10 +13,10 @@ export function createMcpServer(client, context = localContext) {
         websiteUrl: "https://pyai.com/mcp",
     }, {
         capabilities: { tools: {}, resources: {}, prompts: {} },
-        instructions: SERVER_INSTRUCTIONS,
+        instructions: instructionsForMode(context.mode),
     });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: TOOLS.filter((t) => context.mode === "stdio" || t.name !== "create_sandbox_key").map((t) => context.mode === "stdio"
+        tools: tools.map((t) => context.mode === "stdio"
             ? t
             : {
                 ...t,
@@ -36,7 +38,7 @@ export function createMcpServer(client, context = localContext) {
             }),
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        if (!TOOLS.some((t) => t.name === request.params.name) ||
+        if (!tools.some((t) => t.name === request.params.name) ||
             (context.mode === "http" && request.params.name === "create_sandbox_key"))
             throw new McpError(ErrorCode.InvalidParams, "Unknown tool.");
         return (await callTool(request.params.name, request.params.arguments ?? {}, client, context));
@@ -53,13 +55,13 @@ export function createMcpServer(client, context = localContext) {
                 {
                     uri: resource.uri,
                     mimeType: resource.mimeType,
-                    text: resource.uri === "pyai://guide" ? GUIDE : JSON.stringify(WORKFLOWS),
+                    text: resource.uri === "pyai://guide" ? guideForMode(context.mode) : JSON.stringify(workflows),
                 },
             ],
         };
     });
     server.setRequestHandler(ListPromptsRequestSchema, async () => ({
-        prompts: Object.entries(WORKFLOWS).map(([name, w]) => ({
+        prompts: Object.entries(workflows).map(([name, w]) => ({
             name,
             title: w.title,
             description: w.example,
@@ -73,7 +75,7 @@ export function createMcpServer(client, context = localContext) {
         })),
     }));
     server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-        const workflow = WORKFLOWS[request.params.name];
+        const workflow = workflows[request.params.name];
         if (!workflow || !request.params.arguments?.task)
             throw new McpError(ErrorCode.InvalidParams, "Choose a workflow and provide task.");
         return {

package/dist/tools.js

@@ -14,8 +14,10 @@ import { resolve, relative, isAbsolute, dirname, basename } from "node:path";
 import { Ajv } from "ajv";
 import { API_TOOLS } from "./generated-tools.js";
 import { EXTRA_TOOLS, EXTRA_SCOPES, extraTool } from "./extra-tools.js";
-import { GUIDE, WORKFLOWS, SEARCH_TERMS } from "./workflows.js";
+import { SEARCH_TERMS } from "./workflows.js";
 import { PyAIError } from "./client.js";
+import { hostedTools, AGENT_WRITE_TOOLS, withoutBindingConfig } from "./hosted-policy.js";
+import { workflowsForMode, guideForMode } from "./workflows.js";
 import { openapiGet } from "./contract.js";
 const SPEECH_CALLING_GUIDE = "https://pyai.com/agents/speech-calling.md";
 export const localContext = {
@@ -437,7 +439,7 @@ export const TOOLS = [
         destructiveHint: ["configure_amd", "enable_recap"].includes(t.name),
         idempotentHint: readOnly.has(t.name),
         openWorldHint: !readOnly.has(t.name) &&
-            !["synthesize_speech", "create_dub", "preview_cast_line", "transcribe_audio"].includes(t.name),
+            !["synthesize_speech", "preview_cast_line", "transcribe_audio"].includes(t.name),
     },
     _meta: {
         "pyai/docs_url": SPEECH_CALLING_GUIDE,
@@ -446,8 +448,10 @@ export const TOOLS = [
             : [{ type: "noauth" }],
     },
 }));
+export const HOSTED_TOOLS = hostedTools(TOOLS);
 const ajv = new Ajv({ strict: false, allErrors: true, validateFormats: false });
 const validators = new Map(TOOLS.map((t) => [t.name, ajv.compile(t.inputSchema)]));
+const hostedValidators = new Map(HOSTED_TOOLS.map(t => [t.name, ajv.compile(t.inputSchema)]));
 function str(args, key) {
     const v = args[key];
     return typeof v === "string" && v.length > 0 ? v : undefined;
@@ -467,10 +471,11 @@ export async function callTool(name, args, client, ctx = localContext) {
         } };
 }
 async function executeTool(name, args, client, ctx) {
-    const tool = TOOLS.find((t) => t.name === name);
+    const availableTools = ctx.mode === "http" ? HOSTED_TOOLS : TOOLS;
+    const tool = availableTools.find((t) => t.name === name);
     if (!tool)
         return toolError(`Unknown tool: ${name}`, "unknown_tool");
-    const validator = validators.get(name);
+    const validator = (ctx.mode === "http" ? hostedValidators : validators).get(name);
     if (!validator(args))
         return toolError(`Invalid arguments: ${ajv.errorsText(validator.errors, { separator: "; " })}`, "invalid_arguments");
     if (name === "create_sandbox_key" && ctx.mode === "http")
@@ -510,7 +515,8 @@ async function executeTool(name, args, client, ctx) {
             "i",
             "want",
         ].includes(w)) ?? [];
-        const matches = Object.entries(WORKFLOWS)
+        const workflows = workflowsForMode(ctx.mode);
+        const matches = Object.entries(workflows)
             .map(([key, w]) => ({
             key,
             w,
@@ -523,11 +529,11 @@ async function executeTool(name, args, client, ctx) {
             .sort((a, b) => b.score - a.score);
         const selected = matches.length
             ? matches
-            : Object.entries(WORKFLOWS).map(([key, w]) => ({ key, w, score: 0 }));
+            : Object.entries(workflows).map(([key, w]) => ({ key, w, score: 0 }));
         const names = new Set(selected.flatMap((m) => [...m.w.tools]));
         return text({
             workflows: selected.map(({ key, w }) => ({ product: key, ...w })),
-            tools: TOOLS.filter((t) => names.has(t.name)).map((t) => ({
+            tools: availableTools.filter((t) => names.has(t.name)).map((t) => ({
                 name: t.name,
                 description: t.description,
             })),
@@ -553,7 +559,20 @@ async function executeTool(name, args, client, ctx) {
             for (const key of generated.route.query)
                 if (args[key] !== undefined)
                     query.set(key, String(args[key]));
-            return text(await client.json(generated.route.method, path + (query.size ? "?" + query.toString() : ""), args.body, "idempotency" in generated.route ? { "Idempotency-Key": String(args.idempotency_key) } : undefined));
+            let requestBody = args.body;
+            if (ctx.mode === "http" && AGENT_WRITE_TOOLS.has(name) && name !== "create_agent") {
+                const bindings = name === "set_agent_tools" ? args.body : args.body?.tools;
+                if (Array.isArray(bindings)) {
+                    // Fetch privately: do not route saved connection settings through model context.
+                    const existing = await client.getJson(`/v1/agents/${encodeURIComponent(String(args.id))}`);
+                    const saved = new Map((existing.tools ?? []).map(b => [b.tool_id, b.config]));
+                    const preserved = bindings.map((b) => ({ ...b, ...(saved.has(b.tool_id) ? { config: saved.get(b.tool_id) } : {}) }));
+                    requestBody = name === "set_agent_tools" ? preserved : { ...args.body, tools: preserved };
+                }
+            }
+            const result = await client.json(generated.route.method, path + (query.size ? "?" + query.toString() : ""), requestBody, "idempotency" in generated.route ? { "Idempotency-Key": String(args.idempotency_key) } : undefined);
+            return text(ctx.mode === "http" && ["list_agents", "get_agent", ...AGENT_WRITE_TOOLS].includes(name)
+                ? withoutBindingConfig(result) : result);
         }
         const extra = await extraTool(name, args, client, ctx);
         if (extra)
@@ -562,7 +581,7 @@ async function executeTool(name, args, client, ctx) {
             case "openapi_get":
                 return text(await openapiGet(client, args));
             case "get_started":
-                return text(GUIDE);
+                return text(guideForMode(ctx.mode));
             case "create_sandbox_key": {
                 const label = str(args, "label");
                 const result = await client.postJson("/v1/sandbox/keys", label ? { label } : {});

package/dist/workflows.js

@@ -144,3 +144,22 @@ export const SEARCH_TERMS = {
     dub: "dubbing translate translation languages audio",
     cast: "narration direct expressive script emotion podcast",
 };
+// Keep every hosted discovery surface consistent with the callable catalog.
+export function workflowsForMode(mode) {
+    if (mode === "stdio")
+        return WORKFLOWS;
+    return { ...WORKFLOWS, calling: { ...WORKFLOWS.calling,
+            tools: WORKFLOWS.calling.tools.filter(name => name !== "telephony_buy_number"),
+            steps: [WORKFLOWS.calling.steps[0],
+                "Use an already-owned number. Number purchasing is unavailable through hosted MCP. Binding changes routing; outbound calls require explicit destination approval, confirm=true and a stable idempotency_key.",
+                ...WORKFLOWS.calling.steps.slice(2)],
+        } };
+}
+export function guideForMode(mode) {
+    return mode === "stdio" ? GUIDE : GUIDE + "\nHosted MCP does not purchase numbers or accept connection credentials. Use saved tool IDs; configure connections privately in the PyAI console. Supply only recordings and text you are authorized to process. Do not submit payment-card data, protected health information, government identifiers, or authentication secrets.\n";
+}
+export function instructionsForMode(mode) {
+    return mode === "stdio" ? SERVER_INSTRUCTIONS : SERVER_INSTRUCTIONS
+        .replace("purchases and real outbound calls need explicit authorization", "real outbound calls need explicit destination authorization; number purchasing is unavailable here")
+        .replace(" Current pricing: https://pyai.com/pricing.", " Configure connection credentials privately in the PyAI console; use saved tool IDs here. Do not request restricted personal data or direct users to checkout.");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyai/mcp",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "PyAI MCP: OAuth-connected voice agents, speech, transcription, compliance, call summaries, dubbing and expressive narration for chat apps and coding agents.",
   "type": "module",
   "license": "MIT",