MCP Server Development Protocol

🚀 Build and share your MCP servers with the world. Once you’ve created a great MCP server, submit it to the Sixth MCP Marketplace to make it discoverable and one-click installable by thousands of developers.

What Are MCP Servers?

Model Context Protocol (MCP) servers extend AI assistants like Sixth by giving them the ability to:

Access external APIs and services
Retrieve real-time data
Control applications and local systems
Perform actions beyond what text prompts alone can achieve

Without MCP, AI assistants are powerful but isolated. With MCP, they gain the ability to interact with virtually any digital system.

The Development Protocol

The heart of effective MCP server development is following a structured protocol. This protocol is implemented through a .sixthrules file that lives at the root of your MCP working directory (/Users/your-name/Documents/Sixth/MCP).

Using `.sixthrules` Files

A .sixthrules file is a special configuration that Sixth reads automatically when working in the directory where it’s placed. These files:

Configure Sixth’s behavior and enforce best practices
Switch Sixth into a specialized MCP development mode
Provide a step-by-step protocol for building servers
Implement safety measures like preventing premature completion
Guide you through planning, implementation, and testing phases

Here’s the complete MCP Server Development Protocol that should be placed in your .sixthrules file:

# MCP Server Development Protocol

⚠️ CRITICAL: DO NOT USE attempt_completion BEFORE TESTING ⚠️

## Step 1: Planning (PLAN MODE)

-   What problem does this tool solve?
-   What API/service will it use?
-   What are the authentication requirements?
    □ Standard API key
    □ OAuth (requires separate setup script)
    □ Other credentials

## Step 2: Implementation (ACT MODE)

1. Bootstrap

    - For web services, JavaScript integration, or Node.js environments:
        ```bash
        npx @modelcontextprotocol/create-server my-server
        cd my-server
        npm install
        ```
    - For data science, ML workflows, or Python environments:
        ```bash
        pip install mcp
        # Or with uv (recommended)
        uv add "mcp[cli]"
        ```

2. Core Implementation

    - Use MCP SDK
    - Implement comprehensive logging
        - TypeScript (for web/JS projects):
            ```typescript
            console.error("[Setup] Initializing server...")
            console.error("[API] Request to endpoint:", endpoint)
            console.error("[Error] Failed with:", error)
            ```
        - Python (for data science/ML projects):
            ```python
            import logging
            logging.error('[Setup] Initializing server...')
            logging.error(f'[API] Request to endpoint: {endpoint}')
            logging.error(f'[Error] Failed with: {str(error)}')
            ```
    - Add type definitions
    - Handle errors with context
    - Implement rate limiting if needed

3. Configuration

    - Get credentials from user if needed
    - Add to MCP settings:

        - For TypeScript projects:
            ```json
            {
            	"mcpServers": {
            		"my-server": {
            			"command": "node",
            			"args": ["path/to/build/index.js"],
            			"env": {
            				"API_KEY": "key"
            			},
            			"disabled": false,
            			"autoApprove": []
            		}
            	}
            }
            ```
        - For Python projects:

            ```bash
            # Directly with command line
            mcp install server.py -v API_KEY=key

            # Or in settings.json
            {
              "mcpServers": {
                "my-server": {
                  "command": "python",
                  "args": ["server.py"],
                  "env": {
                    "API_KEY": "key"
                  },
                  "disabled": false,
                  "autoApprove": []
                }
              }
            }
            ```

## Step 3: Testing (BLOCKER ⛔️)

<thinking>
BEFORE using attempt_completion, I MUST verify:
□ Have I tested EVERY tool?
□ Have I confirmed success from the user for each test?
□ Have I documented the test results?

If ANY answer is "no", I MUST NOT use attempt_completion.
</thinking>

1. Test Each Tool (REQUIRED)
   □ Test each tool with valid inputs
   □ Verify output format is correct
   ⚠️ DO NOT PROCEED UNTIL ALL TOOLS TESTED

## Step 4: Completion

❗ STOP AND VERIFY:
□ Every tool has been tested with valid inputs
□ Output format is correct for each tool

Only after ALL tools have been tested can attempt_completion be used.

## Key Requirements

-   ✓ Must use MCP SDK
-   ✓ Must have comprehensive logging
-   ✓ Must test each tool individually
-   ✓ Must handle errors gracefully
-   ⛔️ NEVER skip testing before completion

When this .sixthrules file is present in your working directory, Sixth will:

Start in PLAN MODE to design your server before implementation
Enforce proper implementation patterns in ACT MODE
Require testing of all tools before allowing completion
Guide you through the entire development lifecycle

Getting Started

Creating an MCP server requires just a few simple steps to get started:

1. Create a `.sixthrules` file (🚨 IMPORTANT)

First, add a .sixthrules file to the root of your MCP working directory using the protocol above. This file configures Sixth to use the MCP development protocol when working in this folder.

2. Start a Chat with a Clear Description

Begin your Sixth chat by clearly describing what you want to build. Be specific about:

The purpose of your MCP server
Which API or service you want to integrate with
Any specific tools or features you need

For example:

I want to build an MCP server for the AlphaAdvantage financial API.
It should allow me to get real-time stock data, perform technical
analysis, and retrieve company financial information.

3. Work Through the Protocol

Sixth will automatically start in PLAN MODE, guiding you through the planning process:

Discussing the problem scope
Reviewing API documentation
Planning authentication methods
Designing tool interfaces

When ready, switch to ACT MODE using the toggle at the bottom of the chat to begin implementation.

4. Provide API Documentation Early

One of the most effective ways to help Sixth build your MCP server is to share official API documentation right at the start:

Here's the API documentation for the service:
[Paste API documentation here]

Providing comprehensive API details (endpoints, authentication, data structures) significantly improves Sixth’s ability to implement an effective MCP server.

Understanding the Two Modes

PLAN MODE

In this collaborative phase, you work with Sixth to design your MCP server:

Define the problem scope
Choose appropriate APIs
Plan authentication methods
Design the tool interfaces
Determine data formats

ACT MODE

Once planning is complete, Sixth helps implement the server:

Set up the project structure
Write the implementation code
Configure settings
Test each component thoroughly
Finalize documentation

Case Study: AlphaAdvantage Stock Analysis Server

Let’s walk through the development process of our AlphaAdvantage MCP server, which provides stock data analysis and reporting capabilities.

Planning Phase

During the planning phase, we:

Defined the problem: Users need access to financial data, stock analysis, and market insights directly through their AI assistant
Selected the API: AlphaAdvantage API for financial market data
- Standard API key authentication
- Rate limits of 5 requests per minute (free tier)
- Various endpoints for different financial data types
Designed the tools needed:
- Stock overview information (current price, company details)
- Technical analysis with indicators (RSI, MACD, etc.)
- Fundamental analysis (financial statements, ratios)
- Earnings report data
- News and sentiment analysis
Planned data formatting:
- Clean, well-formatted markdown output
- Tables for structured data
- Visual indicators (↑/↓) for trends
- Proper formatting of financial numbers

Implementation

We began by bootstrapping the project:

npx @modelcontextprotocol/create-server alphaadvantage-mcp
cd alphaadvantage-mcp
npm install axios node-cache

Next, we structured our project with:

src/
  ├── api/
  │   └── alphaAdvantageClient.ts  # API client with rate limiting & caching
  ├── formatters/
  │   └── markdownFormatter.ts     # Output formatters for clean markdown
  └── index.ts                     # Main MCP server implementation

API Client Implementation

The API client implementation included:

Rate limiting: Enforcing the 5 requests per minute limit
Caching: Reducing API calls with strategic caching
Error handling: Robust error detection and reporting
Typed interfaces: Clear TypeScript types for all data

Key implementation details:

/**
 * Manage rate limiting based on free tier (5 calls per minute)
 */
private async enforceRateLimit() {
  if (this.requestsThisMinute >= 5) {
    console.error("[Rate Limit] Rate limit reached. Waiting for next minute...");
    return new Promise<void>((resolve) => {
      const remainingMs = 60 * 1000 - (Date.now() % (60 * 1000));
      setTimeout(resolve, remainingMs + 100); // Add 100ms buffer
    });
  }

  this.requestsThisMinute++;
  return Promise.resolve();
}

Markdown Formatting

We implemented formatters to display financial data beautifully:

/**
 * Format company overview into markdown
 */
export function formatStockOverview(overviewData: any, quoteData: any): string {
	// Extract data
	const overview = overviewData
	const quote = quoteData["Global Quote"]

	// Calculate price change
	const currentPrice = parseFloat(quote["05. price"] || "0")
	const priceChange = parseFloat(quote["09. change"] || "0")
	const changePercent = parseFloat(quote["10. change percent"]?.replace("%", "") || "0")

	// Format markdown
	let markdown = `# ${overview.Symbol} (${overview.Name}) - ${formatCurrency(currentPrice)} ${addTrendIndicator(priceChange)}${changePercent > 0 ? "+" : ""}${changePercent.toFixed(2)}%\n\n`

	// Add more details...

	return markdown
}

Tool Implementation

We defined five tools with clear interfaces:

server.setRequestHandler(ListToolsRequestSchema, async () => {
	console.error("[Setup] Listing available tools")

	return {
		tools: [
			{
				name: "get_stock_overview",
				description: "Get basic company info and current quote for a stock symbol",
				inputSchema: {
					type: "object",
					properties: {
						symbol: {
							type: "string",
							description: "Stock symbol (e.g., 'AAPL')",
						},
						market: {
							type: "string",
							description: "Optional market (e.g., 'US')",
							default: "US",
						},
					},
					required: ["symbol"],
				},
			},
			// Additional tools defined here...
		],
	}
})

Each tool’s handler included:

Input validation
API client calls with error handling
Markdown formatting of responses
Comprehensive logging

Testing Phase

This critical phase involved systematically testing each tool:

First, we configured the MCP server in the settings:

{
	"mcpServers": {
		"alphaadvantage-mcp": {
			"command": "node",
			"args": ["/path/to/alphaadvantage-mcp/build/index.js"],
			"env": {
				"ALPHAVANTAGE_API_KEY": "YOUR_API_KEY"
			},
			"disabled": false,
			"autoApprove": []
		}
	}
}

Then we tested each tool individually:

get_stock_overview: Retrieved AAPL stock overview information

# AAPL (Apple Inc) - $241.84 ↑+1.91%

**Sector:** TECHNOLOGY
**Industry:** ELECTRONIC COMPUTERS
**Market Cap:** 3.63T
**P/E Ratio:** 38.26
...

get_technical_analysis: Obtained price action and RSI data

# Technical Analysis: AAPL

## Daily Price Action

Current Price: $241.84 (↑$4.54, +1.91%)

### Recent Daily Prices

| Date       | Open    | High    | Low     | Close   | Volume |
| ---------- | ------- | ------- | ------- | ------- | ------ |
| 2025-02-28 | $236.95 | $242.09 | $230.20 | $241.84 | 56.83M |

...

get_earnings_report: Retrieved MSFT earnings history and formatted report

# Earnings Report: MSFT (Microsoft Corporation)

**Sector:** TECHNOLOGY
**Industry:** SERVICES-PREPACKAGED SOFTWARE
**Current EPS:** $12.43

## Recent Quarterly Earnings

| Quarter    | Date       | EPS Estimate | EPS Actual | Surprise % |
| ---------- | ---------- | ------------ | ---------- | ---------- |
| 2024-12-31 | 2025-01-29 | $3.11        | $3.23      | ↑4.01%     |

...

Challenges and Solutions

During development, we encountered several challenges:

API Rate Limiting:
- Challenge: Free tier limited to 5 calls per minute
- Solution: Implemented queuing, enforced rate limits, and added comprehensive caching
Data Formatting:
- Challenge: Raw API data not user-friendly
- Solution: Created formatting utilities for consistent display of financial data
Timeout Issues:
- Challenge: Complex tools making multiple API calls could timeout
- Solution: Suggested breaking complex tools into smaller pieces, optimizing caching

Lessons Learned

Our AlphaAdvantage implementation taught us several key lessons:

Plan for API Limits: Understand and design around API rate limits from the beginning
Cache Strategically: Identify high-value caching opportunities to improve performance
Format for Readability: Invest in good data formatting for improved user experience
Test Every Path: Test all tools individually before completion
Handle API Complexity: For APIs requiring multiple calls, design tools with simpler scopes

Core Implementation Best Practices

Comprehensive Logging

Effective logging is essential for debugging MCP servers:

// Start-up logging
console.error("[Setup] Initializing AlphaAdvantage MCP server...")

// API request logging
console.error(`[API] Getting stock overview for ${symbol}`)

// Error handling with context
console.error(`[Error] Tool execution failed: ${error.message}`)

// Cache operations
console.error(`[Cache] Using cached data for: ${cacheKey}`)

Strong Typing

Type definitions prevent errors and improve maintainability:

export interface AlphaAdvantageConfig {
	apiKey: string
	cacheTTL?: Partial<typeof DEFAULT_CACHE_TTL>
	baseURL?: string
}

/**
 * Validate that a stock symbol is provided and looks valid
 */
function validateSymbol(symbol: unknown): asserts symbol is string {
	if (typeof symbol !== "string" || symbol.trim() === "") {
		throw new McpError(ErrorCode.InvalidParams, "A valid stock symbol is required")
	}

	// Basic symbol validation (letters, numbers, dots)
	const symbolRegex = /^[A-Za-z0-9.]+$/
	if (!symbolRegex.test(symbol)) {
		throw new McpError(ErrorCode.InvalidParams, `Invalid stock symbol: ${symbol}`)
	}
}

Intelligent Caching

Reduce API calls and improve performance:

// Default cache TTL in seconds
const DEFAULT_CACHE_TTL = {
	STOCK_OVERVIEW: 60 * 60, // 1 hour
	TECHNICAL_ANALYSIS: 60 * 30, // 30 minutes
	FUNDAMENTAL_ANALYSIS: 60 * 60 * 24, // 24 hours
	EARNINGS_REPORT: 60 * 60 * 24, // 24 hours
	NEWS: 60 * 15, // 15 minutes
}

// Check cache first
const cachedData = this.cache.get<T>(cacheKey)
if (cachedData) {
	console.error(`[Cache] Using cached data for: ${cacheKey}`)
	return cachedData
}

// Cache successful responses
this.cache.set(cacheKey, response.data, cacheTTL)

Graceful Error Handling

Implement robust error handling that maintains a good user experience:

try {
	switch (request.params.name) {
		case "get_stock_overview": {
			// Implementation...
		}

		// Other cases...

		default:
			throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`)
	}
} catch (error) {
	console.error(`[Error] Tool execution failed: ${error instanceof Error ? error.message : String(error)}`)

	if (error instanceof McpError) {
		throw error
	}

	return {
		content: [
			{
				type: "text",
				text: `Error: ${error instanceof Error ? error.message : String(error)}`,
			},
		],
		isError: true,
	}
}

MCP Resources

Resources let your MCP servers expose data to Sixth without executing code. They’re perfect for providing context like files, API responses, or database records that Sixth can reference during conversations.

Adding Resources to Your MCP Server

Define the resources your server will expose:

server.setRequestHandler(ListResourcesRequestSchema, async () => {
	return {
		resources: [
			{
				uri: "file:///project/readme.md",
				name: "Project README",
				mimeType: "text/markdown",
			},
		],
	}
})

Implement read handlers to deliver the content:

server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
	if (request.params.uri === "file:///project/readme.md") {
		const content = await fs.promises.readFile("/path/to/readme.md", "utf-8")
		return {
			contents: [
				{
					uri: request.params.uri,
					mimeType: "text/markdown",
					text: content,
				},
			],
		}
	}

	throw new Error("Resource not found")
})

Resources make your MCP servers more context-aware, allowing Sixth to access specific information without requiring you to copy/paste. For more information, refer to the official documentation.

Common Challenges and Solutions

API Authentication Complexities

Challenge: APIs often have different authentication methods. Solution:

For API keys, use environment variables in the MCP configuration
For OAuth, create a separate script to obtain refresh tokens
Store sensitive tokens securely

// Authenticate using API key from environment
const API_KEY = process.env.ALPHAVANTAGE_API_KEY
if (!API_KEY) {
	console.error("[Error] Missing ALPHAVANTAGE_API_KEY environment variable")
	process.exit(1)
}

// Initialize API client
const apiClient = new AlphaAdvantageClient({
	apiKey: API_KEY,
})

Missing or Limited API Features

Challenge: APIs may not provide all the functionality you need. Solution:

Implement fallbacks using available endpoints
Create simulated functionality where necessary
Transform API data to match your needs

API Rate Limiting

Challenge: Most APIs have rate limits that can cause failures. Solution:

Implement proper rate limiting
Add intelligent caching
Provide graceful degradation
Add transparent errors about rate limits

if (this.requestsThisMinute >= 5) {
	console.error("[Rate Limit] Rate limit reached. Waiting for next minute...")
	return new Promise<void>((resolve) => {
		const remainingMs = 60 * 1000 - (Date.now() % (60 * 1000))
		setTimeout(resolve, remainingMs + 100) // Add 100ms buffer
	})
}

​What Are MCP Servers?

​The Development Protocol

​Using .sixthrules Files

​Getting Started

​1. Create a .sixthrules file (🚨 IMPORTANT)

​2. Start a Chat with a Clear Description

​3. Work Through the Protocol

​4. Provide API Documentation Early

​Understanding the Two Modes

​PLAN MODE

​ACT MODE

​Case Study: AlphaAdvantage Stock Analysis Server

​Planning Phase

​Implementation

​API Client Implementation

​Markdown Formatting

​Tool Implementation

​Testing Phase

​Challenges and Solutions

​Lessons Learned

​Core Implementation Best Practices

​Comprehensive Logging

​Strong Typing

​Intelligent Caching

​Graceful Error Handling

​MCP Resources

​Adding Resources to Your MCP Server

​Common Challenges and Solutions

​API Authentication Complexities

​Missing or Limited API Features

​API Rate Limiting

​Additional Resources