> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myweave.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup Guide

> Configure myweave MCP server in your AI tools

## MCP Server Endpoints

myweave provides multiple endpoints for AI integration:

| Endpoint                           | Purpose    | Use Case                                          |
| ---------------------------------- | ---------- | ------------------------------------------------- |
| `https://docs.myweave.ai/llms.txt` | AI Sitemap | Index of all documentation pages for AI crawlers  |
| `https://docs.myweave.ai/mcp`      | MCP Server | Real-time documentation queries and API execution |

***

## Available MCP Tools

When you connect to myweave's MCP server, your AI can execute this tool:

| Tool Name | API Endpoint | What It Does                    |
| --------- | ------------ | ------------------------------- |
| `chat`    | POST /chat   | Start or continue conversations |

<Note>
  These tools are defined in our OpenAPI specification and automatically exposed through the MCP server.
  Your AI can execute them directly when you ask questions or give commands.
</Note>

### Example Tool Usage

**Ask your AI to execute tools:**

```
"Start a chat with coach_123 about leadership"
→ Executes: chat tool
→ API Call: POST /chat
→ Result: Returns thread ID and streaming expert response

// other tools are currently not exposed via MCP
```

<Note>
  The AI automatically maps your natural language requests to the appropriate MCP tool,
  constructs the correct API call, handles authentication, and returns the results.
</Note>

***

## Claude Desktop Setup

### Step 1: Locate Configuration File

* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
* **Linux**: `~/.config/Claude/claude_desktop_config.json`

### Step 2: Add myweave MCP Server

Edit the file and add:

```json theme={null}
{
  "mcpServers": {
    "myweave": {
      "command": "npx",
      "args": ["-y", "@mintlify/mcp-server", "https://docs.myweave.ai"]
    }
  }
}
```

<Note>
  When Claude executes a myweave API call, it will prompt you for a JWT (Bearer token) per our OpenAPI security. The AI agent handles attaching it.
</Note>

### Step 3: Restart Claude Desktop

Close and reopen Claude Desktop for changes to take effect.

### Step 4: Test the Integration

Ask Claude:

```
"What APIs does myweave provide?"

"How do I authenticate with myweave?"

"Show me how to start a chat with an expert"
```

Claude will query the MCP server and provide accurate, up-to-date answers from your documentation.

### Example Prompts

**Generate Integration Code:**

```
"Write a TypeScript function to start a chat with a myweave expert 
and handle the streaming response"
```

**Query API Details:**

```
"What parameters does the myweave /chat endpoint accept?"

"Show me the response format for getting user threads"
```

**Execute MCP Tools (Requires API Key):**

```
"Start a conversation with a leadership coach about team management"
→ Uses MCP tool: chat

"Get all my conversation threads for user_123"
→ Uses MCP tool: get-user-threads

"Show me messages from my latest thread"
→ Uses MCP tool: threads (get-thread-messages has been removed, use threads endpoint instead)
```

**Claude's Response:**

```
Claude: "I'll help you start a conversation. To execute this, I need your myweave API key."
You: [Provide API key]
Claude: "Starting chat with leadership coach..."
Claude: [Executes POST /chat via MCP]
Claude: "Thread created! The coach says: [expert response]"
```

***

## Cursor IDE Setup

### Step 1: Install MCP Extension

In Cursor, install the MCP extension for Model Context Protocol support.

### Step 2: Configure MCP Server

Create or edit `.cursor/mcp.json` in your project:

```json theme={null}
{
  "servers": {
    "myweave-docs": {
      "command": "npx",
      "args": ["-y", "@mintlify/mcp-server", "https://docs.myweave.ai"]
    }
  }
}
```

<Note>
  When Cursor executes a myweave API call, it will prompt you for a JWT based on the OpenAPI security requirements. The AI handles authentication internally.
</Note>

### Step 3: Restart Cursor

### Step 4: Use in Development

Now when coding, Cursor can:

* Query myweave docs automatically
* Generate integration code
* Provide accurate API examples
* Reference latest endpoint specifications

### Example Usage in Cursor

While coding:

```typescript theme={null}
// Type a comment:
// TODO: integrate myweave chat API

// Cursor (using MCP):
// Queries docs.myweave.ai
// Generates complete implementation
// Includes error handling and types
```

Ask in chat:

```
"Add myweave expert chat to this React component"

"Show me how to upload files to myweave knowledge base"
```

***

## Custom MCP Client

### Build Your Own MCP Client

**Step 1: Install MCP SDK**

```bash theme={null}
npm install @modelcontextprotocol/sdk
```

**Step 2: Create MCP Client**

```typescript theme={null}
import { MCPClient } from '@modelcontextprotocol/sdk';

// Initialize myweave MCP client
const myweaveClient = new MCPClient({
  serverUrl: 'https://docs.myweave.ai/mcp'
});

// Query documentation (no auth needed)
async function queryDocs(question: string) {
  const response = await myweaveClient.queryDocs({
    query: question,
    context: "myweave API"
  });
  
  return response;
}

// Execute API call - client handles auth prompting
async function executeAPICall(endpoint: string, params: any) {
  // MCP client will prompt for credentials when needed
  // based on OpenAPI security requirements
  const response = await myweaveClient.executeAPI({
    endpoint: endpoint,
    method: "POST",
    body: params
  });
  
  return response;
}
```

<Note>
  Your MCP client will automatically prompt for the required JWT (Authorization: Bearer) when executing API calls.
</Note>

**Step 3: Use in Your AI App**

```typescript theme={null}
// Example: AI app that integrates human expertise
class HybridAIApp {
  async respond(userMessage: string) {
    // AI analyzes message
    const aiResponse = await this.llm.generate(userMessage);
    
    // Check if human expertise needed
    if (this.needsHumanExpert(userMessage)) {
      // Query myweave docs via MCP (no auth needed)
      const docs = await queryDocs("How to start expert chat?");
      
      // Execute expert consultation
      // MCP client handles auth - will prompt for JWT if needed
      const expertChat = await executeAPICall("/chat", {
        message: userMessage,
        context: { coachId: "expert_123" }
      });
      
      // Combine AI + human intelligence
      return this.synthesize(aiResponse, expertChat);
    }
    
    return aiResponse;
  }
}
```

**How Authentication Works:**

* MCP client reads that `/chat` requires Bearer auth (from OpenAPI spec)
* Prompts user for a JWT (or uses cached credential)
* Automatically includes `Authorization: Bearer token` in requests

***

## Direct llms.txt Integration

For simpler integrations without full MCP protocol:

### Load Documentation Index

```javascript theme={null}
// Fetch documentation index
const response = await fetch('https://docs.myweave.ai/llms.txt');
const index = await response.text();

console.log(index);
// Returns structured list of all documentation pages
```

### Load Complete Documentation

```javascript theme={null}
// Fetch all documentation at once
const response = await fetch('https://docs.myweave.ai/llms-full.txt');
const fullDocs = await response.text();

// Use with your LLM for context
const llmResponse = await openai.chat.completions.create({
  model: "gpt-4",
  messages: [
    {
      role: "system",
      content: `You are a myweave API integration assistant. 
                Here is the complete documentation:\n\n${fullDocs}`
    },
    {
      role: "user",
      content: "How do I authenticate and start a chat?"
    }
  ]
});
```

***

## Authentication

### What You Need

myweave API requires authentication for all API requests:

* **API Key** - Required header: `X-API-Key`
* **JWT Token** - Optional header: `Authorization: Bearer` (for user-specific requests)

Get your API key: [support@myweave.ai](mailto:support@myweave.ai?subject=API%20Key%20Request)

### How It Works

When your AI agent tries to execute a myweave API call through MCP:

1. **AI reads OpenAPI spec** → Sees that `X-API-Key` header is required
2. **AI prompts you** → "Please provide your myweave API key"
3. **You provide the key** → AI stores it securely for the session
4. **AI executes API call** → Includes `X-API-Key: your_key` header automatically
5. **Request goes to myweave** → Your API authenticates and processes the request

**The AI agent handles authentication internally** based on the security requirements defined in our OpenAPI specification.

<Note>
  Your API key is handled by your AI tool (Claude, Cursor, etc.) and sent directly to
  myweave's API. The MCP server just serves the documentation—authentication happens
  between the AI agent and myweave API.
</Note>

<Note>
  For complete details on authentication methods, JWT tokens, login flows, and token refresh,
  see the [Authentication Guide](/authentication).
</Note>

***

## Verification

After configuring MCP, test that it's working:

**Test 1: Documentation Query**

```
Ask your AI: "What MCP tools does myweave provide?"
```

**Expected Response:**

```
The myweave MCP server provides 4 tools:
1. chat - Start or continue conversations with experts
2. get-user-threads - List all conversation threads for a user
3. threads - Get full message history from a thread (replaces get-thread-messages)
4. upload-knowledge - Upload files to knowledge base

[Detailed information about each tool...]
```

**Test 2: Code Generation**

```
Ask your AI: "Write a function to start a chat with myweave using the MCP chat tool"
```

**Expected:** AI generates accurate code using latest API structure and MCP tool.

**Test 3: MCP Tool Execution (Requires API Key)**

```
Ask your AI: "Use the chat tool to start a conversation with coach_123 about leadership"
```

**Expected Flow:**

```
Claude: "To execute the chat tool, I need your myweave API key"
You: [Provide API key]
Claude: [Executes chat tool via MCP]
Claude: "Conversation started! Thread ID: 550e8400... The expert says: [response]"
```

**Test 4: List Available Tools**

```
Ask your AI: "What tools are available in the myweave MCP server?"
```

**Expected:** AI lists the 4 MCP tools (chat, get-user-threads, threads, upload-knowledge)

***

## Troubleshooting

<Accordion title="MCP server not responding">
  **Symptoms:**

  * AI says it can't access myweave documentation
  * No response when asking about myweave

  **Solutions:**

  1. **Check Configuration File Path**
     * Ensure you edited the correct config file
     * Verify JSON syntax is valid (no trailing commas, proper quotes)

  2. **Restart Your AI Application**
     * Close and completely restart Claude Desktop or Cursor
     * Some changes require a full restart

  3. **Test Manually**
     ```bash theme={null}
     curl https://docs.myweave.ai/llms.txt
     ```
     Should return documentation index.

  4. **Check Network Connection**
     * Ensure you have internet access
     * Check if firewall is blocking the connection
</Accordion>

<Accordion title="Authentication errors when executing API calls">
  **Symptoms:**

  * "401 Unauthorized" errors
  * "Missing or invalid API key"
  * API calls fail but doc queries work

  **Solutions:**

  1. **Provide API Key When Prompted**
     * When your AI asks for API key, provide it
     * The AI will store it securely for the session

  2. **Verify API Key is Valid**
     Test your API key manually:
     ```bash theme={null}
     curl -X POST https://api.myweave.ai/functions/v1/chat \
       -H "X-API-Key: your_key_here" \
       -H "Content-Type: application/json" \
       -d '{"message":"test","context":{"coachId":"coach_123"}}'
     ```

  3. **Request New API Key**
     If your key is invalid, request a new one from [support@myweave.ai](mailto:support@myweave.ai)

  4. **Check for Typos**
     * Ensure you copied the full API key
     * No extra spaces or line breaks
     * API keys start with specific prefixes (check your key format)
</Accordion>

<Accordion title="JWT token expired">
  **Symptoms:**

  * "Token expired" errors
  * User-specific requests failing
  * Works initially, then stops after \~1 hour

  **Solutions:**

  1. **Refresh Your JWT Token**
     See the [Authentication Guide](/authentication) for token refresh flow

  2. **Provide New Token to AI**
     When prompted, provide the refreshed JWT token

  3. **For Long Sessions**
     Implement automatic token refresh in your application.
     See [Authentication Guide](/authentication#long-lived-sessions--token-refresh).
</Accordion>

<Accordion title="AI not finding myweave documentation">
  **Symptoms:**

  * AI says "I don't have information about myweave"
  * Queries return generic responses instead of specific docs

  **Solutions:**

  1. **Use Explicit References**
     Try: "Using the myweave MCP server, show me how to start a chat"

  2. **Verify MCP Server Name**
     * Check that server name in config matches what you reference
     * Try: "Using @myweave, show me the API endpoints"

  3. **Check MCP is Actually Configured**
     * Ensure config file has `mcpServers` section
     * Verify no JSON syntax errors

  4. **Test with Simple Query**
     Try: "List all available MCP servers"
     Should show "myweave" if configured correctly
</Accordion>

<Accordion title="Can't execute API calls (only doc queries work)">
  **Why This Happens:**

  * Some MCP clients only support documentation queries
  * API execution requires additional permissions
  * API key may not be properly configured

  **Solutions:**

  1. **Verify API Execution is Supported**
     * Claude Desktop: ✅ Supports API execution
     * Cursor: ⚠️ May be documentation-only (check version)
     * Custom clients: ✅ Depends on implementation

  2. **Provide API Key When Prompted**
     Ensure you provide the correct API key when the AI tool asks for it.

  3. **Use Custom Client for Full Control**
     Build your own MCP client for complete API execution support.
     See [Examples](/mcp/examples) for complete implementations.
</Accordion>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Use Cases" icon="lightbulb" href="/mcp/use-cases">
    See real-world examples of hybrid AI apps
  </Card>

  <Card title="Code Examples" icon="code" href="/mcp/examples">
    Complete implementations for TypeScript, Python, React
  </Card>

  <Card title="Chat API" icon="message-circle" href="/api-reference/chat">
    Explore all API endpoints
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Learn about API keys and JWT tokens
  </Card>
</CardGroup>

***

## Get API Access

Ready to build AI apps that integrate human expertise?

<Card title="Request API Key" icon="key" href="mailto:support@myweave.ai?subject=API%20Key%20Request">
  Email [support@myweave.ai](mailto:support@myweave.ai) to get your API key and start building
</Card>