add mcp guide

README.md

@@ -12,7 +12,7 @@ This repository contains the comprehensive documentation for ElizaOS, including:
 - **API Reference** - Complete API documentation for all modules
 - **Examples** - Real-world implementations and patterns
 
-## 🚀 Development
+## Development
 
 ### Prerequisites
 
@@ -71,7 +71,7 @@ We welcome contributions to improve the ElizaOS documentation! Here's how you ca
 - Test all code snippets
 - Add images/diagrams for complex concepts
 
-## 🚢 Publishing Changes
+## Publishing Changes
 
 Changes are automatically deployed when merged to the main branch. The documentation is hosted using Mintlify's infrastructure.
 

development.mdx

@@ -99,9 +99,9 @@ elizaos plugins add @elizaos/plugin-twitter
 elizaos plugins add @elizaos/plugin-discord
 ```
 
-<Warning>
-  After installing plugins via CLI, you **must** add them to your character file (`.json` or `.ts`) to activate them:
-</Warning>
+<Info>
+  After installing plugins, you must add them to your character configuration to activate them. See [Plugin Management](/cli-reference/plugins) for complete installation details.
+</Info>
 
 ```json character.json
 {

docs.json

@@ -62,6 +62,7 @@
               "guides/compose-state-guide",
               "guides/sessions-api-guide",
               "guides/socket-io-integration-guide",
+              "guides/mcp-setup-guide",
               {
                 "group": "Plugin Migration (0.x to 1.x)",
                 "icon": "arrow-right-arrow-left",

guides/mcp-setup-guide.mdx

@@ -0,0 +1,196 @@
+---
+title: MCP Setup Guide
+description: Learn how to set up Model Context Protocol (MCP) with ElizaOS to give your agents external tool capabilities
+icon: puzzle-piece
+---
+
+## What is MCP?
+
+MCP (Model Context Protocol) allows your ElizaOS agent to use external tools and services. Think of it as giving your agent abilities like web search, file access, or API connections.
+
+## Quick Setup
+
+### Step 1: Install the MCP Plugin
+
+```bash
+bun add @elizaos/plugin-mcp
+```
+
+### Step 2: Add MCP to Your Character
+
+Add `'@elizaos/plugin-mcp'` to your character's plugins array:
+
+```typescript
+export const character: Character = {
+  name: 'YourAgent',
+  plugins: [
+    '@elizaos/plugin-sql',
+    '@elizaos/plugin-openrouter',
+    '@elizaos/plugin-openai',
+    '@elizaos/plugin-bootstrap',
+    '@elizaos/plugin-mcp', // Add this
+    // ... other plugins
+  ],
+  // ... rest of configuration
+};
+```
+
+## Example 1: STDIO Server (Firecrawl for Web Search)
+
+STDIO servers run as local processes and communicate through standard input/output.
+
+### Configuration
+
+```typescript
+export const character: Character = {
+  name: 'WebSearchAgent',
+  plugins: [
+    '@elizaos/plugin-sql',
+    '@elizaos/plugin-openrouter',
+    '@elizaos/plugin-openai',
+    '@elizaos/plugin-mcp',
+    '@elizaos/plugin-bootstrap',
+  ],
+  settings: {
+    mcp: {
+      servers: {
+        firecrawl: {
+          type: 'stdio',
+          command: 'npx',
+          args: ['-y', 'firecrawl-mcp'],
+          env: {
+            // Optional: Add your Firecrawl API key if you have one
+            FIRECRAWL_API_KEY: process.env.FIRECRAWL_API_KEY || '',
+          },
+        },
+      },
+    },
+  },
+  system: 'You are a helpful assistant with web search capabilities.',
+};
+```
+
+### What It Can Do
+
+- Search the web for current information
+- Extract content from websites
+- Perform deep research on topics
+- Scrape structured data
+
+### Usage Examples
+
+```text
+User: "Search for the latest AI news"
+Agent: *searches the web and provides current information*
+
+User: "What's on example.com?"
+Agent: *scrapes and summarizes the website content*
+```
+
+## Example 2: SSE Server (Remote API Connection)
+
+SSE (Server-Sent Events) servers connect to remote APIs through HTTP.
+
+### Configuration
+
+```typescript
+export const character: Character = {
+  name: 'APIAgent',
+  plugins: ['@elizaos/plugin-sql', '@elizaos/plugin-mcp', '@elizaos/plugin-bootstrap'],
+  settings: {
+    mcp: {
+      servers: {
+        myApiServer: {
+          type: 'sse',
+          url: 'https://your-api-server.com/sse', // Replace with your SSE server URL
+        },
+      },
+    },
+  },
+  system: 'You are a helpful assistant with API access capabilities.',
+};
+```
+
+### What It Can Do
+
+Depends on the specific SSE server, but typically:
+
+- Real-time data access
+- API interactions
+- Custom tool execution
+- Dynamic resource fetching
+
+### Usage Examples
+
+```text
+User: "Get the latest data from the API"
+Agent: *fetches and returns real-time data*
+
+User: "Execute the custom tool"
+Agent: *runs the tool provided by the SSE server*
+```
+
+## Complete Example
+
+Here's a complete character configuration with both server types:
+
+```typescript
+import { type Character } from '@elizaos/core';
+
+export const character: Character = {
+  name: 'Eliza',
+  plugins: [
+    '@elizaos/plugin-sql',
+    ...(process.env.ANTHROPIC_API_KEY ? ['@elizaos/plugin-anthropic'] : []),
+    ...(process.env.OPENAI_API_KEY ? ['@elizaos/plugin-openai'] : []),
+    '@elizaos/plugin-bootstrap',
+    '@elizaos/plugin-mcp',
+  ],
+  settings: {
+    mcp: {
+      servers: {
+        // STDIO server example - runs locally
+        firecrawl: {
+          type: 'stdio',
+          command: 'npx',
+          args: ['-y', 'firecrawl-mcp'],
+          env: {},
+        },
+        // SSE server example - connects to remote API
+        customApi: {
+          type: 'sse',
+          url: 'https://your-api.com/sse',
+        },
+      },
+    },
+  },
+  system: 'You are a helpful assistant with access to web search and API tools.',
+  bio: [
+    'Can search the web for information',
+    'Can connect to external APIs',
+    'Provides helpful responses',
+  ],
+};
+```
+
+## How to Test
+
+1. Start your agent:
+
+```bash
+bun run start
+```
+
+2. Ask your agent to use the tools:
+   - For web search: "Search for [topic]"
+   - For API tools: Use commands specific to your SSE server
+
+## Troubleshooting
+
+- **Server not connecting**: Check that the command/URL is correct
+- **Tools not available**: Ensure `@elizaos/plugin-mcp` is in your plugins array
+- **Permission errors**: For STDIO servers, ensure the command can be executed
+
+## That's It!
+
+You now have MCP set up with your ElizaOS agent. Each MCP server adds different capabilities - just add them to your `settings.mcp.servers` configuration.

guides/plugin-developer-guide.mdx

@@ -100,7 +100,7 @@ plugin-my-plugin/
 
 Selecting "Full Plugin" adds frontend capabilities:
 
-```
+```text
 plugin-my-plugin/
 ├── src/
 │   ├── index.ts           # Plugin manifest with routes

guides/sessions-api-guide.mdx

@@ -1,6 +1,7 @@
 ---
 title: Sessions API Guide
 description: Learn how to use the Sessions API for persistent, stateful conversations with ElizaOS agents
+icon: messages
 ---
 
 The Sessions API provides a way to create persistent, stateful conversations with ElizaOS agents. Unlike direct messaging, sessions maintain conversation context and state across multiple interactions, enabling more coherent and contextual conversations.

plugins/bootstrap/message-flow.mdx

@@ -267,7 +267,7 @@ await runtime.evaluate(message, state, shouldRespond, callback, responseMessages
 
 ### 1. Should Respond Decision Tree
 
-```
+```text
 Is DM? → YES → Respond
 Is Voice DM? → YES → Respond
 Is API Call? → YES → Respond
@@ -280,14 +280,14 @@ Run shouldRespond LLM →
 
 ### 2. Response Type Decision
 
-```
+```text
 Actions = [REPLY] only AND Providers = [] → Simple Response
 Otherwise → Complex Response with Action Processing
 ```
 
 ### 3. Evaluator Trigger Conditions
 
-```
+```text
 Message Count > ConversationLength / 4 → Run Reflection
 New Interaction → Update Relationships
 Facts Mentioned → Extract and Store

plugins/platform/twitter/examples.mdx

@@ -23,7 +23,7 @@ const character = {
   clients: ["twitter"],
   postExamples: [
     "Just thinking about the future of technology...",
-    "Building something new today! 🚀",
+    "Building something new today!",
     "The best code is no code, but sometimes you need to write some.",
     "Learning something new every day keeps the mind sharp."
   ],