Skip to main content
Glama
vishutorvi

MCP Learning Project

by vishutorvi
OverviewSchemaRelated ServersScoreDiscussions
JavaScript

MCP Learning Project - Complete Guide

This is a comprehensive tutorial project that teaches Model Context Protocol (MCP) development from beginner to advanced levels. You'll learn both server-side (backend) and client-side (frontend) development.

🎯 What You'll Learn

Beginner Level:

  • ✅ Basic MCP server structure and concepts

  • ✅ Simple tool creation and registration

  • ✅ Parameter handling and validation

  • ✅ Basic client connection and tool calling

Intermediate Level:

  • ✅ State management between tool calls

  • ✅ Resource management (serving data to AI)

  • ✅ Data processing and complex operations

  • ✅ Client-server communication patterns

Advanced Level:

  • ✅ CRUD operations with persistent state

  • ✅ Comprehensive error handling

  • ✅ Prompt templates for AI interactions

  • ✅ Best practices and production considerations

Related MCP server: MCP Learning Project

📁 Project Structure

mcp-learning-project/
├── src/
│   ├── server.ts          # MCP Learning Server (backend)
│   └── client.ts          # MCP Learning Client (frontend)
├── dist/                  # Compiled JavaScript
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
└── README.md             # This file

🚀 Quick Start

1. Setup Project

# Create project directory
mkdir mcp-learning-project
cd mcp-learning-project

# Initialize npm project
npm init -y

# Install dependencies
npm install @modelcontextprotocol/sdk

# Install dev dependencies
npm install --save-dev typescript @types/node tsx

2. Create Package.json

{
  "name": "mcp-learning-project",
  "version": "1.0.0",
  "description": "Learn MCP development from beginner to advanced",
  "main": "dist/server.js",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start:server": "node dist/server.js",
    "start:client": "node dist/client.js dist/server.js",
    "dev:server": "tsx src/server.ts",
    "dev:client": "tsx src/client.ts dist/server.js",
    "demo": "npm run build && npm run start:client"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^0.4.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "tsx": "^4.0.0",
    "typescript": "^5.0.0"
  }
}

3. Create TypeScript Config

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

4. Save the Code Files

  • Save the MCP Learning Server code as src/server.ts

  • Save the MCP Learning Client code as src/client.ts

5. Build and Run

# Build the project
npm run build

# Run the interactive client (this will also start the server)
npm run demo

🎓 Learning Path

Phase 1: Understanding the Basics

  1. Start the interactive client:

    npm run demo

  2. Try basic commands:

    mcp-learning> help
mcp-learning> tools
mcp-learning> call hello_world {"name": "Alice"}

  3. Learn about resources:

    mcp-learning> resources
mcp-learning> read mcp-concepts

Phase 2: Hands-on Practice

  1. Run the beginner demo:

    mcp-learning> demo beginner

  2. Practice tool calls:

    mcp-learning> call calculator {"operation": "add", "a": 5, "b": 3}
mcp-learning> call calculator {"operation": "divide", "a": 10, "b": 0}

  3. Understand state management:

    mcp-learning> call counter {"action": "get"}
mcp-learning> call counter {"action": "increment", "amount": 5}
mcp-learning> call counter {"action": "get"}

Phase 3: Advanced Concepts

  1. Run intermediate demo:

    mcp-learning> demo intermediate

  2. Work with complex data:

    mcp-learning> call data_processor {"data": [5, 2, 8, 1, 9], "operation": "sort"}
mcp-learning> call data_processor {"data": [5, 2, 8, 1, 9], "operation": "average"}

  3. CRUD operations:

    mcp-learning> call task_manager {"action": "create", "task": {"title": "Learn MCP", "priority": "high"}}
mcp-learning> call task_manager {"action": "list"}

Phase 4: Production Ready

  1. Run advanced demo:

    mcp-learning> demo advanced

  2. Learn error handling:

    mcp-learning> call error_demo {"error_type": "none"}
mcp-learning> call error_demo {"error_type": "validation"}

  3. Study best practices:

    mcp-learning> read best-practices

🔧 Key Concepts Explained

1. MCP Server (Backend)

The server provides capabilities to AI models:

// Server setup
const server = new Server({
  name: 'my-server',
  version: '1.0.0'
}, {
  capabilities: {
    tools: {},      // Functions AI can call
    resources: {},  // Data AI can read  
    prompts: {}     // Templates AI can use
  }
});

// Tool registration
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'my_tool',
      description: 'What this tool does',
      inputSchema: { /* JSON Schema */ }
    }
  ]
}));

// Tool implementation
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  // Process the tool call and return results
  return {
    content: [{
      type: 'text',
      text: 'Tool response'
    }]
  };
});

2. MCP Client (Frontend)

The client connects to servers and uses their capabilities:

// Client setup
const client = new Client({
  name: 'my-client',
  version: '1.0.0'
}, {
  capabilities: { /* client capabilities */ }
});

// Connect to server
const transport = new StdioClientTransport(/* server process */);
await client.connect(transport);

// Discover server capabilities
const tools = await client.listTools();
const resources = await client.listResources();

// Use server tools
const result = await client.callTool({
  name: 'tool_name',
  arguments: { /* tool parameters */ }
});

3. Communication Flow

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   AI Model  │ ───▶ │ MCP Client  │ ───▶ │ MCP Server  │
│             │      │ (Frontend)  │      │ (Backend)   │
│             │ ◀─── │             │ ◀─── │             │
└─────────────┘      └─────────────┘      └─────────────┘
     ▲                      │                      │
     │                      │                      │
     └──────────────────────┴──────────────────────┘
              Uses server capabilities

🧪 Experimentation Ideas

Create Your Own Tools:

  1. Weather Tool:

    {
  name: 'weather',
  description: 'Get weather information',
  inputSchema: {
    type: 'object',
    properties: {
      city: { type: 'string', description: 'City name' },
      units: { type: 'string', enum: ['celsius', 'fahrenheit'], default: 'celsius' }
    },
    required: ['city']
  }
}

  2. File System Tool:

    {
  name: 'file_operations',
  description: 'Basic file system operations',
  inputSchema: {
    type: 'object',
    properties: {
      action: { type: 'string', enum: ['list', 'read', 'write'] },
      path: { type: 'string', description: 'File or directory path' },
      content: { type: 'string', description: 'Content to write' }
    },
    required: ['action', 'path']
  }
}

  3. Database Tool:

    {
  name: 'database',
  description: 'Simple in-memory database operations',
  inputSchema: {
    type: 'object',
    properties: {
      action: { type: 'string', enum: ['create', 'read', 'update', 'delete'] },
      table: { type: 'string', description: 'Table name' },
      data: { type: 'object', description: 'Data to store/update' },
      id: { type: 'string', description: 'Record ID' }
    },
    required: ['action', 'table']
  }
}

Create Custom Resources:

  1. Configuration Resource:

    {
  uri: 'config://app-settings',
  name: 'Application Settings',
  description: 'Current application configuration',
  mimeType: 'application/json'
}

  2. Documentation Resource:

    {
  uri: 'docs://api-reference',
  name: 'API Reference',
  description: 'Complete API documentation',
  mimeType: 'text/markdown'
}

Create Interactive Prompts:

  1. Code Review Prompt:

    {
  name: 'code-review',
  description: 'Start a code review session',
  arguments: [
    {
      name: 'language',
      description: 'Programming language',
      required: true
    },
    {
      name: 'focus',
      description: 'Review focus (security, performance, style)',
      required: false
    }
  ]
}

🐛 Debugging and Troubleshooting

Common Issues:

  1. Server Won't Start:

    # Check if TypeScript compiled correctly
npm run build

# Look for compilation errors
npx tsc --noEmit

# Check for missing dependencies
npm install

  2. Client Can't Connect:

    # Make sure server path is correct
node dist/client.js dist/server.js

# Check if server process starts
node dist/server.js

  3. Tool Calls Fail:

    // Add debugging to your server
console.error(`[DEBUG] Tool called: ${name}`, JSON.stringify(args));

// Validate input parameters carefully
if (typeof args.requiredParam === 'undefined') {
  throw new McpError(ErrorCode.InvalidParams, 'Missing required parameter');
}

Debug Mode:

Enable verbose logging in both server and client:

// In server
console.error('[SERVER]', 'Detailed log message');

// In client  
console.log('[CLIENT]', 'Connection status:', connected);

🚀 Next Steps: Building Production Servers

1. Add Real Functionality:

Replace demo tools with actual useful functionality:

// Example: Real file system access
private async handleFileOperations(args: any) {
  const { action, path, content } = args;
  
  switch (action) {
    case 'read':
      return {
        content: [{
          type: 'text',
          text: await fs.readFile(path, 'utf-8')
        }]
      };
    case 'write':
      await fs.writeFile(path, content);
      return {
        content: [{
          type: 'text', 
          text: `File written: ${path}`
        }]
      };
  }
}

2. Add External Integrations:

// Example: HTTP API integration
private async handleApiCall(args: any) {
  const { url, method, data } = args;
  
  const response = await fetch(url, {
    method,
    headers: { 'Content-Type': 'application/json' },
    body: data ? JSON.stringify(data) : undefined
  });
  
  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        status: response.status,
        data: await response.json()
      }, null, 2)
    }]
  };
}

3. Add Persistence:

import * as fs from 'fs/promises';

class PersistentMCPServer {
  private dataFile = './mcp-data.json';
  
  async loadState(): Promise<Map<string, any>> {
    try {
      const data = await fs.readFile(this.dataFile, 'utf-8');
      return new Map(Object.entries(JSON.parse(data)));
    } catch {
      return new Map();
    }
  }
  
  async saveState(state: Map<string, any>): Promise<void> {
    const data = Object.fromEntries(state);
    await fs.writeFile(this.dataFile, JSON.stringify(data, null, 2));
  }
}

4. Add Authentication:

private validateAuth(headers: any): boolean {
  const token = headers['authorization'];
  return token === 'Bearer your-secret-token';
}

private async handleSecureTool(args: any, headers: any) {
  if (!this.validateAuth(headers)) {
    throw new McpError(ErrorCode.InvalidParams, 'Authentication required');
  }
  
  // Continue with tool logic...
}

📚 Additional Resources

Official Documentation:

Community Examples:

Advanced Topics:

  • HTTP transport for web services

  • WebSocket transport for real-time communication

  • Custom transport implementations

  • Performance optimization techniques

  • Security best practices

🎯 Learning Exercises

Exercise 1: Extend the Calculator

Add more operations: power, sqrt, factorial, sin, cos

Exercise 2: Build a Note-Taking System

Create tools for creating, editing, searching, and organizing notes with tags.

Exercise 3: Add External API Integration

Integrate with a real API (weather, news, stock prices) and create corresponding tools.

Exercise 4: Build a Project Manager

Create a comprehensive project management system with tasks, deadlines, priorities, and progress tracking.

Exercise 5: Add Real-Time Features

Implement tools that can send notifications or updates back to the client.

🏆 Mastery Checklist

Beginner Level ✅

  • Understand MCP architecture (client, server, transport)

  • Create basic tools with input validation

  • Handle simple tool calls and responses

  • Read and understand error messages

Intermediate Level ✅

  • Implement stateful tools with persistence

  • Create and serve resources to AI

  • Handle complex data processing

  • Implement proper error handling patterns

Advanced Level ✅

  • Build CRUD operations with complex state

  • Create interactive prompt templates

  • Implement production-ready error handling

  • Understand security and authentication concepts

  • Optimize performance for production use

Expert Level 🚀

  • Build custom transport layers

  • Create MCP server frameworks

  • Implement advanced security measures

  • Build distributed MCP architectures

  • Contribute to the MCP ecosystem

🎉 Congratulations!

You now have a complete understanding of MCP development from both frontend and backend perspectives. You can:

  • Build MCP servers that provide tools, resources, and prompts

  • Create MCP clients that interact with servers effectively

  • Handle errors gracefully and implement proper validation

  • Manage state between tool calls and across sessions

  • Follow best practices for production-ready implementations

The interactive learning environment in this project gives you hands-on experience with all MCP concepts. Use this as a foundation to build your own specialized MCP servers for any domain or use case!

Happy coding! 🚀

Available Tools

6 tools
calculatorC

Perform basic math operations

ParametersJSON Schema
NameRequiredDescriptionDefault
aYesFirst number
bYesSecond number
operationYesMath operation to perform

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the single-sentence description does not disclose behavioral traits such as error handling (e.g., division by zero), precision limitations, or return format. This is a significant gap for a tool that performs operations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with one sentence, no unnecessary words. It is front-loaded but perhaps overly brief, missing context that would improve utility.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple 3-parameter schema and no output schema, the description is minimally adequate. However, it lacks information on error behavior and result format, which would be helpful for an AI agent. Sibling tools are diverse, so context is not critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the description does not need to add much. It adds no extra meaning beyond the schema, which already describes the parameters well. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Perform basic math operations' clearly indicates the tool's purpose as a calculator for fundamental arithmetic. It is generic but distinct from siblings like 'hello_world' and 'counter'. The schema provides specific operations, but the description could be more precise.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives, nor any exclusions (e.g., for complex math). The description lacks context about appropriate usage scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

counterC

Manage a counter with state persistence

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesCounter action
amountNoAmount to increment/decrement (default: 1)

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The phrase 'with state persistence' hints at behavioral aspects, but without annotations, the description does not disclose other traits such as side effects, authorization needs, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words, achieving high conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, no annotations, and 2 parameters, the description fails to explain return values (e.g., for 'get'), initial state, or error conditions, leaving gaps for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the description adds no additional meaning beyond the enum and default value. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Manage a counter with state persistence' uses a generic verb 'manage' and doesn't specify the operations (increment, decrement, etc.) nor distinguish from sibling tools like 'calculator' or 'data_processor'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like 'calculator' or 'task_manager'. The description lacks context for appropriate usage scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

data_processorC

Process arrays of data with various operations

ParametersJSON Schema
NameRequiredDescriptionDefault
dataYesArray of numbers to process
operationYesOperation to perform on data

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description must disclose behavioral traits. It only says 'process,' which implies computation but does not state that the tool is non-destructive, pure, or specify return values. The operation enum hints at behavior, but the description adds no transparency beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence and front-loaded, but it is under-informative. Every word is used, but the sentence lacks substance to be truly concise; it sacrifices completeness for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (two params, no nesting), but no output schema exists. The description fails to mention what the tool returns (e.g., a number for sum/average/max/min, or sorted array for sort). This missing information makes the description incomplete for an agent to use effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds no new meaning beyond restating the schema ('arrays of data' and 'various operations'). It does not elaborate on parameter formats, constraints, or relationships.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies 'Process arrays of data with various operations,' which clearly indicates the tool operates on arrays with multiple operations. The verb 'process' is generic, but combined with the schema details, the purpose is clear. However, it does not explicitly differentiate from sibling tools like 'calculator' which might also manipulate numbers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description does not mention use cases, prerequisites, or exclusions. The agent is left to infer usage from the schema and tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

error_demoC

Demonstrate different types of error handling

ParametersJSON Schema
NameRequiredDescriptionDefault
error_typeYesType of error to demonstrate

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral disclosure. It only says 'demonstrate' but fails to explain what happens—whether errors are returned, thrown, or simulated. No side effects or safety information is given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, concise but vague. It lacks necessary detail to be fully actionable, making it marginally acceptable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple demo tool with one parameter and no output schema, the description should explain what the tool returns or simulates. It does not specify behavior or expected outcomes, leaving the agent with incomplete context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with one parameter fully described via enum. The description adds no extra meaning beyond the schema, which already lists valid values. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Demonstrate different types of error handling' clearly states the verb (demonstrate) and resource (error handling). It is specific enough to distinguish from sibling tools like hello_world or calculator, which have unrelated purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidelines are provided. The description does not indicate when to use this tool versus alternatives, nor does it specify prerequisites or context for demonstration.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hello_worldC

A simple greeting tool to understand MCP basics

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesName to greet

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, and the description does not disclose behavioral traits such as side effects, return value, or state changes. The user must infer behavior from the name and parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence. However, it could be slightly more informative without becoming verbose, earning a 4.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple hello world tool, the description is adequate but lacks details on return value or behavior. Given the simplicity, a 3 is reasonable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with the parameter 'name' described as 'Name to greet'. The description adds no extra meaning beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'A simple greeting tool to understand MCP basics' gives a general idea but doesn't explicitly state it returns a greeting. It is distinct from sibling tools like calculator or counter, but the purpose is vague without specifying the output.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like calculator or counter. The description lacks context for usage scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

task_managerB

Manage a list of tasks with CRUD operations

ParametersJSON Schema
NameRequiredDescriptionDefault
idNoTask ID for read/update/delete operations
taskNoTask object for create/update operations
actionYesTask management action

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It only mentions 'CRUD operations' but does not disclose specific behaviors like side effects, permissions, or error handling. The description adds minimal value beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no wasted words. It is front-loaded with the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although the schema is rich, the description is too brief to fully equip an AI agent. It does not explain how the action parameter maps to required fields or provide a complete picture of usage flow, missing critical context for a tool with multiple operations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds no additional meaning beyond what the schema provides, earning a baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool manages a list of tasks with CRUD operations, using a specific verb ('Manage') and resource ('tasks'). It distinguishes itself from unrelated sibling tools like 'hello_world' and 'calculator'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. The description only states what it does, without specifying which action to choose for different scenarios or when to avoid using it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 6 tool updatesv1.0.0
    • First observedcalculator
    • First observedcounter
    • First observeddata_processor
    • First observederror_demo
    • First observedhello_world
    • First observedtask_manager
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0
Disambiguation5/5

Each tool has a distinct purpose: greeting, arithmetic, stateful counter, data array operations, task CRUD, and error demonstration. No overlap exists, making selection unambiguous.

Naming Consistency5/5

All tool names are snake_case compound nouns (hello_world, calculator, counter, data_processor, task_manager, error_demo), forming a predictable pattern consistent throughout.

Tool Count5/5

With 6 tools, the set is well-scoped for a learning project, covering a variety of fundamental concepts without being overwhelming or sparse.

Completeness5/5

The tool suite covers key MCP basics: simple output, computation, state persistence, data manipulation, CRUD operations, and error handling. No obvious gaps for an introductory demo.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • MCP-Guide

    qpd-v
    A
    license
    B
    quality
    D
    maintenance
    A beginner-friendly Model Context Protocol (MCP) server that helps users understand MCP concepts, provides interactive examples, and lists available MCP servers. This server is designed to be a helpful companion for developers working with MCP. Also comes with a huge list of servers you can install.
    3
    24
    66
    Apache 2.0

  • MCP Learning Project

    RobertBauer-dev
    F
    license
    Not graded
    quality
    D
    maintenance
    A tutorial MCP server for learning the Model Context Protocol by building file and system tools. Provides hands-on experience creating custom tools that enable AI models to interact with files and execute system commands.
    -

  • MCP Learning Project

    BerdTan
    A
    license
    Not graded
    quality
    D
    maintenance
    A comprehensive learning platform for Model Context Protocol development that teaches MCP concepts through hands-on modules including text processing, file operations, and database integration. Designed as an educational tool with progressive difficulty levels from basic to advanced MCP server development.
    MIT

  • MCPServerTransportDemo

    barwalgayatri02
    F
    license
    Not graded
    quality
    D
    maintenance
    A demonstration project for building and testing Model Context Protocol (MCP) servers using the MCP inspector and client tools. It provides a practical implementation for exploring MCP transport mechanisms and server-client interactions.
    -

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/vishutorvi/mcp-learning-project'

If you have feedback or need assistance with the MCP directory API, please join our Discord server