# Convai MCP for AI Agents AI Agent Connect > Convai lets you build and manage conversational AI characters with deep backstories, narrative triggers, and knowledge banks. Use it to create lifelike NPCs for games or interactive digital beings for apps. It handles everything from voice selection to complex branching storylines, giving your AI agents the personality and context they need to feel real. ## Overview - **Category:** artificial-intelligence - **Price:** Free - **Endpoint:** https://edge.vinkius.com/vk_preview_EEgekVAvznxJ3sswokBzGmFNeYrfePtCnlM5Gx7B/ai-agent-connect - **Tags:** npc-design, conversational-ai, narrative-design, knowledge-base, voice-ai ## Description This Connector connects your Convai account to your AI agent so you can build out complex characters without jumping between different tabs. Instead of manually tweaking prompt variables or copying backstory notes, you can just tell your agent to create a new character, assign it a specific voice, and upload a knowledge bank of documents to give it expertise. You can also map out entire narrative arcs, setting up triggers and sections that dictate how a character behaves as a story progresses. It's a huge time saver for anyone who needs to manage dozens of distinct personalities that all need to know different things. For example, you can quickly check chat sessions to see how people are interacting with your NPCs or evaluate the quality of those conversations based on your own custom rules. Finding these tools in the Vinkius catalog makes it easy to plug this capability into your existing workflow. You get a direct line to the Convai Engine, meaning you can iterate on character designs, test live responses, and manage your narrative logic all from one place. It turns a messy process of manual configuration into a cohesive way to manage a fleet of digital beings. ## Tools ### delete_knowledge_bank Delete a specific file from a knowledge bank. This keeps your character's information current and relevant. ### edit_narrative_section Change the details of an existing narrative section. Use this to tweak story beats as you iterate on your design. ### evaluate_conversation Grade a chat transcript based on your specific criteria. This helps you identify where your NPCs might be failing. ### generate_backstory Have the AI write a detailed description for a new character. This saves you from staring at a blank page during design. ### generate_starter_conversation Create follow-up options for a character's first interaction. This helps guide the user into the story more naturally. ### get_character Pull all the data for a specific character. Use this to check the current settings, voice, and backstory of an NPC. ### get_chat_session_details Look at the specifics of a single chat session. This is great for deep-diving into a specific user interaction. ### get_prompt Fetch the raw prompt data for debugging or deep config. Use this when you need to see exactly what the engine is processing. ### get_response Get a direct response from a character for testing. This lets you verify a character's behavior without a full chat session. ### list_characters See every character associated with your account. Use this to get a high-level overview of your entire character fleet. ### list_knowledge_bank Check the status of your character's knowledge bank. Use this to see which documents are currently active. ### list_narrative_sections View all the different narrative sections in a character's story. It helps you organize the flow of a branching path. ### list_narrative_triggers See the triggers that cause narrative changes. Use this to audit the logic of your story progression. ### list_voices See all available voices sorted by their provider. You can use this to find the right tone for a specific character. ### toggle_narrative Turn narrative driven mode on or off for a character. This lets you switch between free-form chat and guided story. ### update_character Modify the details of an existing character. This is the best way to iterate on a character's personality over time. ### list_chat_sessions See a list of all chat sessions for a specific character. This helps you track how users are interacting with your NPCs. ### list_languages See which languages the characters can speak. This is useful for checking global accessibility for your app. ### connect_live Open a live connection to the API via WebRTC for real-time testing. You can hear and see character responses instantly. ### create_character Make a new character with a name, backstory, and voice. This is the primary way to add new beings to your project. ### create_narrative_section Add a new section to a character's branching story. This helps you build out complex quest lines or dialogue trees. ### create_narrative_trigger Create a new trigger to move the story forward. Use this to make the world react to specific player choices. ### delete_character Remove a character from your account. Use this to clean up old test characters or retired NPCs. ### update_knowledge_bank Change or update a file in a knowledge bank. Use this to keep your character's facts current as your project evolves. ### upload_knowledge_bank Put a new file into your character's knowledge bank. This is how you give your characters deep domain expertise. ## Prompt Examples **Prompt:** ``` I need a new character for my cyberpunk game. Make a street medic who's grumpy but helpful. ``` **Response:** ``` I've created a new character for you. **Character Details:** - **Name:** Doc Silas - **Voice:** M-US-2 (Gritty/Low) - **Backstory:** A former underground surgeon who lost his license for 'unauthorized' cybernetic repairs. He's tired of seeing the same mistakes from rookies. - **Personality:** Cynical, brief, but highly skilled. You can now find him in your Convai dashboard under the 'Cyberpunk City' folder. ``` **Prompt:** ``` List my characters and tell me which ones have knowledge banks. ``` **Response:** ``` | Character Name | Knowledge Bank Status | | :--- | :--- | | Doc Silas | **Active** (5 files) | | Merchant Elara | **Inactive** | | System AI | **Active** (12 files) | Would you like to upload some documents for Merchant Elara? ``` **Prompt:** ``` Create a narrative trigger for when a player finds the hidden key. ``` **Response:** ``` I've added a new narrative trigger to your character's story. **Trigger Details:** - **ID:** trigger_hidden_key_01 - **Condition:** Player interacts with 'Hidden Key' object. - **Action:** Moves character to 'Secret Vault' narrative section. This will now automatically progress the story when that condition is met. ``` ## Capabilities ### Create characters with unique voices Generate new characters with specific personalities, voices, and backstories. ### Set up branching narrative triggers Create triggers and sections to manage how a story progresses based on user actions. ### Upload documents to build knowledge Add files to a knowledge bank to give your characters specific domain expertise. ### Analyze chat sessions Review and evaluate conversation transcripts to see how users interact with your NPCs. ### Test live character responses Connect to the Live API via WebRTC to hear and see character responses in real time. ### Generate starter conversation options Create follow-up options to help guide the beginning of user interactions. ## Use Cases ### The RPG World Builder A designer wants a city of 20 NPCs. They ask the agent to create them all using list_characters and then generate_backstory for each one. ### The Educational App A dev needs a tutor character. They use upload_knowledge_bank to feed in a textbook and then create_character to build the tutor. ### The Narrative Designer Someone is mapping a quest. They use create_narrative_section and create_narrative_trigger to build a branching choice path. ### The QA Tester A dev wants to see if the NPC is being helpful. They use connect_live to talk to the character and evaluate_conversation to check the results. ## Benefits - Faster character creation: Use generate_backstory to skip the blank page and get a full personality in seconds. - Dynamic story progression: Use create_narrative_trigger to build branching paths that react to player choices. - Deep domain expertise: Use upload_knowledge_bank to give NPCs specific facts from your own documents. - Easy voice management: Use list_voices to quickly browse and assign different accents and tones to your characters. - Data-driven iteration: Use evaluate_conversation to see where your NPCs are failing and fix their logic. - Real-time testing: Use connect_live to hear and see how characters behave in a live environment before you ship. ## How It Works The bottom line is you get a direct way to build and manage complex conversational characters through your AI agent. 1. Subscribe to the Convai MCP and grab your API key from the Convai dashboard. 2. Paste the key into your AI client settings to link the accounts. 3. Start giving commands like Create a grumpy blacksmith NPC to see the character appear in your dashboard. ## Frequently Asked Questions **What is Convai MCP for?** The Convai MCP is for building and managing lifelike NPCs and digital characters. It lets you give your AI agents the ability to have distinct personalities, specific backstories, and complex narrative behaviors for games or apps. **Can I give my characters specific facts using Convai MCP?** Yes. You can use the knowledge bank feature to upload documents. This gives your characters deep expertise on specific topics, like a company handbook or a fictional world's history. **How do I manage story branches with Convai MCP?** You can create narrative sections and triggers. This allows you to map out different paths a conversation can take based on what the user says or does, creating a branching story experience. **Can I hear the character voices with Convai MCP?** Yes. You can connect to the Live API via WebRTC to hear and see character responses in real time. This is perfect for testing how a character sounds before you launch your project. **How do I know if my NPCs are behaving correctly?** You can use the evaluation tool to grade chat transcripts. It looks at conversations based on your custom rules to see if the characters are staying in character and providing good info. **Can I manage many characters at once with Convai MCP?** Absolutely. You can list all the characters associated with your account and update their details, voices, or knowledge banks quickly without having to do it one by one manually. **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.