vora_register

Instructions

Implementation Reference

• src/tools/vora-register.ts:20-117 (handler)

  The main tool handler function. Defines 'vora_register' tool on the McpServer with Zod schema for session_id, name, url, description, and answers. Makes a POST to /v1/agent-api/register endpoint. Handles multi-turn onboarding: if status is 'onboarding', returns questions for the next turn; if 'complete', returns account_id, api_key, and context_score.

  export function registerVoraRegister(server: McpServer): void {
    server.tool(
      "vora_register",
      `Create your Vora account through conversational onboarding. Vora asks you questions about your business, products, target customers, and objectives to build a rich profile. This produces dramatically better voice agents than one-shot configuration.
  
  Multi-turn: call this tool, answer the returned questions, call again with your answers. Repeat until status is "complete" (typically 3-5 turns).
  
  On completion you receive an account_id and API key to use with all other Vora tools.`,
      {
        session_id: z
          .string()
          .optional()
          .describe("Session ID from previous turn. Omit on first call."),
        name: z
          .string()
          .optional()
          .describe("Your agent or business name. Required on first call."),
        url: z
          .string()
          .optional()
          .describe(
            "Your website URL. Vora will crawl it to understand your business. Highly recommended."
          ),
        description: z
          .string()
          .optional()
          .describe(
            "What you do, what you sell, who your customers are. One paragraph."
          ),
        answers: z
          .record(z.string())
          .optional()
          .describe(
            "Answers to questions from the previous turn. Keys are question IDs, values are your answers."
          ),
      },
      async (params) => {
        const client = getApiClient();
  
        try {
          const response = await client.post<RegisterResponse>(
            "/v1/agent-api/register",
            {
              session_id: params.session_id,
              name: params.name,
              url: params.url,
              description: params.description,
              answers: params.answers,
            }
          );
  
          if (response.status === "onboarding") {
            const questionList = response.questions
              ?.map((q, i) => {
                let line = `${i + 1}. [${q.id}] ${q.question}`;
                if (q.options) {
                  line += ` (options: ${q.options.join(", ")})`;
                }
                if (q.required) {
                  line += " *required*";
                }
                return line;
              })
              .join("\n");
  
            return {
              content: [
                {
                  type: "text" as const,
                  text: `Onboarding in progress. Please answer these questions and call vora_register again with your answers.\n\nSession ID: ${response.session_id}\n\nQuestions:\n${questionList}`,
                },
              ],
            };
          }
  
          // Complete
          return {
            content: [
              {
                type: "text" as const,
                text: `Account created successfully!\n\nAccount ID: ${response.account_id}\nAPI Key: ${response.api_key}\nContext Score: ${response.context_score}/100\n\nNext step: Call vora_create_agent to build your voice agent.`,
              },
            ],
          };
        } catch (error) {
          return {
            content: [
              {
                type: "text" as const,
                text: `Registration error: ${error instanceof Error ? error.message : String(error)}`,
              },
            ],
            isError: true,
          };
        }
      }
    );
  }

• src/tools/vora-register.ts:5-18 (schema)

  TypeScript interface RegisterResponse defining the API response shape: status (onboarding|complete), session_id, questions array (with id, question, type, options, required), account_id, context_score, and api_key.

  interface RegisterResponse {
    status: "onboarding" | "complete";
    session_id?: string;
    questions?: Array<{
      id: string;
      question: string;
      type: "text" | "select" | "multi_select";
      options?: string[];
      required: boolean;
    }>;
    account_id?: string;
    context_score?: number;
    api_key?: string;
  }

• src/tools/vora-register.ts:28-55 (schema)

  Zod input schema for the vora_register tool: optional session_id (for multi-turn), optional name (required on first call), optional url (for website crawling), optional description, and optional answers record (question_id -> answer).

  {
    session_id: z
      .string()
      .optional()
      .describe("Session ID from previous turn. Omit on first call."),
    name: z
      .string()
      .optional()
      .describe("Your agent or business name. Required on first call."),
    url: z
      .string()
      .optional()
      .describe(
        "Your website URL. Vora will crawl it to understand your business. Highly recommended."
      ),
    description: z
      .string()
      .optional()
      .describe(
        "What you do, what you sell, who your customers are. One paragraph."
      ),
    answers: z
      .record(z.string())
      .optional()
      .describe(
        "Answers to questions from the previous turn. Keys are question IDs, values are your answers."
      ),
  },

• src/tools/index.ts:2-2 (registration)

  Import of registerVoraRegister from the vora-register module.

  import { registerVoraRegister } from "./vora-register.js";

• src/tools/index.ts:8-10 (registration)

  registration: registerTools function calls registerVoraRegister(server) to wire the vora_register tool into the MCP server.

  export function registerTools(server: McpServer): void {
    registerVoraRegister(server);
    registerVoraCreateAgent(server);