# Convai MCP > Convai lets you build entire conversational AI worlds from scratch. Use this MCP to create complex characters with specific backstories and voices for games or apps. It manages narrative flow, stores deep knowledge in a bank, and allows your agent to test character responses in real-time. ## Overview - **Category:** artificial-intelligence - **Price:** Free - **Tags:** npc-design, conversational-ai, narrative-design, knowledge-base, voice-ai ## Description This connection gives your agent full control over the Convai Engine. You can design entire digital beings; these aren't just simple chatbots. Instead, you build characters with defined backstories, unique voices, and deep expertise drawn from uploaded documents. If you're writing a massive RPG or building an app that needs believable NPCs, this is what you need. You manage everything—from creating the initial character profile using `generate_backstory` to mapping out story triggers and sections for branching narratives. Need to ground your characters in real-world data? Upload documents into the Knowledge Bank and let them reference that information naturally during conversation. When all of this gets complicated, Vinkius makes it easy; you connect once from any MCP-compatible client and get access to the entire Convai toolset, letting your agent do the heavy lifting. ## Tools ### list_chat_sessions Returns a list of previous conversations for a specific character. ### list_knowledge_bank Displays the current status and contents of your uploaded knowledge sources. ### list_languages Shows all language codes that the character is capable of using. ### list_narrative_sections Retrieves a list of every narrative section you've created in your story map. ### list_narrative_triggers Lists all the triggers that control when and how a storyline changes. ### list_voices Returns an inventory of available character voices, categorized by provider. ### toggle_narrative Turns the narrative-driven mode on or off for a specific character. ### connect_live Connects your agent directly to the character's live API endpoint for real-time testing. ### create_character Creates a brand new conversational AI character with specified traits and voices. ### create_narrative_section Builds a structured section of the story that characters can follow or encounter. ### create_narrative_trigger Sets up a specific event or condition that causes the narrative to shift or branch. ### delete_character Removes an existing character profile from your account entirely. ### delete_knowledge_bank Deletes a file or knowledge bank source you uploaded to the system. ### edit_narrative_section Modifies the content and flow of an existing story section. ### evaluate_conversation Runs a chat transcript through criteria to score or analyze its quality. ### generate_backstory Generates detailed character descriptions and histories based on simple prompts. ### generate_starter_conversation Creates multiple follow-up dialogue options to kick off a chat session or test an NPC's opening lines. ### get_character Retrieves all specific details for one character by its ID. ### get_chat_session_details Fetches the full record and history of a completed chat session. ### get_prompt Retrieves configuration data for debugging or advanced setup checks. ### get_response Forces the character to give a specific response based on an input prompt. ### list_characters Lists all characters that are currently active under your account. ### update_character Makes changes to an existing character's traits, backstory, or voice settings. ### update_knowledge_bank Replaces or modifies content within a previously uploaded knowledge source file. ### upload_knowledge_bank Adds a new document or set of files to the character's permanent knowledge base. ## Prompt Examples **Prompt:** ``` List all my Convai characters. ``` **Response:** ``` I've retrieved your characters. You have 3 active characters: 'Cyber Guard' (ID: char_123), 'Merchant Elara' (ID: char_456), and 'System AI' (ID: char_789). ``` **Prompt:** ``` Generate a backstory for a futuristic detective named Jax. ``` **Response:** ``` Using `generate_backstory`... Jax is a former Neo-Tokyo enforcer turned private eye after a high-stakes betrayal. He specializes in tracking rogue synthetics in the neon-lit underbelly of the city. ``` **Prompt:** ``` Show me the details for character ID char_123. ``` **Response:** ``` Fetching details for 'Cyber Guard' (char_123)... Voice: 'M-US-1', Backstory: 'A sentinel programmed to protect the vault...', Model: 'gpt-4o', Temperature: 0.7. ``` ## Capabilities ### Build and edit character profiles Create new characters, update their details, or delete them entirely using specific actions. ### Control story flow and narratives Define plot points, create narrative sections, and set triggers that force the conversation down a specific storyline path. ### Give characters deep knowledge Upload documents to the Knowledge Bank so your NPCs can answer complex questions based on specialized materials. ### Analyze conversations after they happen Review chat transcripts, list session details, and evaluate conversation quality against custom criteria. ### Test characters live Connect in real-time to test how a character responds using `connect_live` or generate sample conversations for testing. ## Use Cases ### Building a fantasy RPG companion A game developer needs an NPC, 'Kael,' who must act like a grizzled mercenary. They use `create_character` to build him and then run `generate_backstory`, feeding the resulting lore back into the character's knowledge base via `upload_knowledge_bank`. Finally, they test his dialogue flow using `get_response` before handing it off to art. ### Creating a complex historical simulation A writer needs characters who only talk about 18th-century trade routes. They use the knowledge bank tools (`upload_knowledge_bank`) to feed in primary source documents and then set up narrative sections that force conversations around those specific topics. ### Debugging customer service dialogue A company researcher wants to ensure their AI support character never gives outdated advice. They `list_knowledge_bank` contents, update the necessary documents using `update_knowledge_bank`, and then use `evaluate_conversation` on old transcripts to check for compliance. ## Benefits - Develop complex lore instantly. Instead of spending hours drafting character profiles in a separate document, you can use `generate_backstory` to create detailed histories right from your agent's prompt window. - Manage story branching without pain. You define narrative sections and triggers (using `create_narrative_section` and `create_narrative_trigger`), telling the AI exactly when and how the plot must change, making your world feel cohesive. - Ground characters in specific facts. By uploading documents using `upload_knowledge_bank`, you ensure that conversations aren't just creative; they are factual, forcing the character to reference your source material. - Test interactions on demand. Need to check how a character responds before a live demo? Use `generate_starter_conversation` or connect via `connect_live` to test dialogue flow right away. - Audit and refine performance. After running beta tests, use `evaluate_conversation` to score transcripts against specific rules. This lets you know exactly which parts of the character's personality are inconsistent. ## How It Works The bottom line is you tell your AI agent what kind of characters and stories you want, and it handles the creation, storage, and deployment through structured calls. 1. Subscribe to the Convai MCP and provide your API key. 2. Connect your agent via any compatible client, granting it access to the character tools. 3. Use commands like `create_character` or `upload_knowledge_bank` to build out your world's lore and knowledge. ## Frequently Asked Questions **How do I start a new character with the Convai MCP using `create_character`?** You call `create_character` and provide the initial details, like their name, voice, and core purpose. This establishes their profile in the system so you can begin building out lore around them. **I need to make sure my character uses specific company rules; which tool should I use?** You must upload those rules or documents using `upload_knowledge_bank`. This ensures the character's knowledge base is restricted and accurate, forcing it to adhere to your source material. **What is the difference between `list_chat_sessions` and `get_chat_session_details`?** `list_chat_sessions` just gives you a list of previous chats for a character. To see what actually happened in one specific chat, you must use `get_chat_session_details`. **How do I make sure my story has multiple possible endings?** You define the flow using narrative tools. Create a main path with `create_narrative_section`, and then set branching points with `create_narrative_trigger` to guide the agent to different outcomes. **Can I test my character's voice live before finalizing it?** Yes. You can connect directly using `connect_live`. This lets you run a real-time chat session and hear how the character's response sounds, which is key for quality control. **If I need to purge old training materials entirely, how do I use the `delete_knowledge_bank` tool?** It permanently removes the specified knowledge bank file from your account. Always run `list_knowledge_bank` first to confirm the ID and status of the material you're removing. **What happens to linked assets, like narratives, when I use the `delete_character` tool?** The character record itself is removed. However, any narrative sections or triggers associated with that ID remain available for re-assignment and reuse. **If I need specific technical metadata about a character, should I use the `get_character` tool?** Yes, this fetches all detailed parameters for an existing character by its ID. This is crucial for debugging or passing precise data structures to other systems. **How do I create a new character with a specific voice?** Use the `create_character` tool. You can specify the `charName`, `backstory`, and `voiceType`. To see available voices, run the `list_voices` query first. **Can I give my character custom documents to learn from?** Yes! Use the `upload_knowledge_bank` tool to add files. Once uploaded, you can link them to your character using the `update_character` tool by passing the document IDs in the `docs` field. **How can I test a character's response to a specific input?** You can use the `get_response` tool. Provide the `charID` and the user text, and the agent will return the character's generated response along with any triggered actions.