Skip to main content
Glama
RossTarrant

mcp-workshop

by RossTarrant
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Build your first MCP server

This workshop is for beginners. You do not need to have used GitHub Copilot or MCP before.

By the end, you will have:

  • used two example tools;

  • created a Python tool of your own; and

  • asked Copilot to run your tool.

What are Copilot, MCP, and tools?

  • GitHub Copilot is an AI assistant inside VS Code. You can type requests into Copilot Chat.

  • An MCP server is a small program that gives Copilot extra abilities.

  • A tool is one of those abilities. In this project, each tool is a Python function.

For example, this server has an add_numbers tool. Copilot can choose that tool, send it two numbers, and show you the answer.

Related MCP server: Demo Server

Part 1: Open the workshop

Use GitHub Codespaces so that everything is installed for you.

  1. Open this repository on GitHub.

  2. Select the green Code button.

  3. Select the Codespaces tab.

  4. Select Create codespace on main.

  5. Wait until VS Code appears and the terminal says: Devcontainer setup complete.

You are now using VS Code in your browser. The files are on the left, the code editor is in the middle, and the terminal is at the bottom.

If GitHub asks you to sign in or enable Copilot, follow the message on screen. Ask your teacher if your account does not have access to Copilot.

Part 2: Open Copilot Chat

  1. Find the Copilot icon near the top of VS Code.

  2. Select it to open Copilot Chat.

  3. If asked to sign in, sign in with your GitHub account.

  4. Type this prompt into the chat box and press Enter:

    Say hello in one short sentence.

If Copilot replies, it is ready.

Part 3: Try the MCP server

This project is already configured to connect the server to Copilot.

  1. Reload VS Code: open the Command Palette with Ctrl+Shift+P, type Developer: Reload Window, and press Enter.

  2. Open Copilot Chat again.

  3. Type this prompt:

    Use the hello_world tool from mcp-workshop.

  4. Copilot may ask for permission to use the tool. Select Allow or Continue.

  5. You should see Hello, world!.

  6. Now type this prompt:

    Use the add_numbers tool from mcp-workshop to add 7 and 5.

You should get 12.

Part 4: Create your own tool

Open src/mcp_workshop/server.py from the file list on the left.

Find the comment that says STEP 3. Directly above that comment, copy and paste this tool:

@mcp.tool()
def favourite_colour(name: str) -> str:
    """Tell someone your favourite colour."""
    return f"{name}, my favourite colour is blue!"

Change blue to your favourite colour, then save the file with Ctrl+S.

What each line means:

  • @mcp.tool() tells the server that Copilot is allowed to use the function.

  • def favourite_colour... gives the tool a name and one input called name.

  • str means the input and answer are text.

  • The text inside """ explains the tool to Copilot.

  • return gives the answer back to Copilot.

Part 5: Use your tool

  1. Reload VS Code again using Developer: Reload Window.

  2. Open Copilot Chat.

  3. Type this prompt:

    Use the favourite_colour tool from mcp-workshop. My name is Alex.

  4. Allow the tool if Copilot asks for permission.

You have built and used your first MCP tool.

Create a tool of your own

Choose something small and fun. For example, your tool could:

  • create a superhero name;

  • convert minutes to seconds;

  • recommend a film genre;

  • calculate the area of a rectangle; or

  • give a random study suggestion.

Use this template:

@mcp.tool()
def your_tool_name(your_input: str) -> str:
    """Explain clearly what your tool does."""
    return "Replace this with your answer"

Change the function name, input, explanation, and returned answer. Save the file, reload VS Code, and ask Copilot to use the new tool.

If something does not work

Try these checks in order:

  1. Copilot does not open: make sure you are signed in to GitHub and ask your teacher to check that you have Copilot access.

  2. Your tool does not appear: save server.py, then reload VS Code.

  3. Copilot does not use the tool: ask it to Use the TOOL_NAME tool from mcp-workshop.

  4. There is a red line in your code: compare your tool with the template. Check the brackets, colon, quotation marks, and indentation.

  5. The server reports an error: undo your latest change with Ctrl+Z, save, and reload VS Code.

  6. It still does not work: show your code and the complete error message to your teacher.

Optional: run the tests

In the terminal at the bottom of VS Code, enter:

pytest

The result should say 2 passed.

Optional: work without Codespaces

Install Python 3.10 or newer, open a terminal in this repository, and run:

python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

On Windows PowerShell, replace the second command with:

.venv\Scripts\Activate.ps1

Available Tools

2 tools
add_numbersAdd two numbersA
Read-onlyIdempotent

Add two numbers together and return the result.

ParametersJSON Schema
NameRequiredDescriptionDefault
first_numberYesThe first number to add.
second_numberYesThe second number to add.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description confirms the tool returns a result without side effects. No additional behavioral details needed beyond consistency.

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?

A single, clear sentence that efficiently conveys the tool's purpose without wasted words. Every element earns its place.

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

Completeness5/5

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

For a simple two-number addition tool with full schema coverage and output schema likely present (though not shown), the description is complete enough to understand the tool's function and inputs.

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 both parameters having descriptions. The tool description adds no extra meaning beyond what the schema provides, resulting in 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 states the exact operation ('add two numbers together and return the result') with a clear verb and resource. The name and title reinforce this. The sibling tool 'hello_world' is unrelated, so no confusion.

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

Usage Guidelines4/5

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

The description does not explicitly state when to use or avoid this tool, but the simple arithmetic nature makes the context obvious. No alternatives are mentioned, but none are needed given the sibling tools.

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

hello_worldHello worldA
Read-onlyIdempotent

Return a friendly Hello, world message.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior3/5

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

Annotations already declare the tool as readOnly, idempotent, and non-destructive. The description adds 'friendly' but no additional behavioral context beyond what annotations convey. For a simple tool, this is adequate but does not exceed the baseline set by annotations.

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, well-structured sentence that efficiently conveys the tool's purpose. It is front-loaded with the action 'Return' and the object 'a friendly Hello, world message'. No redundant words.

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

Completeness5/5

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

Given the tool's trivial nature (no parameters, clear annotations, existing output schema), the description is fully complete. It covers the necessary information for an AI agent to understand and invoke the tool correctly.

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

Parameters4/5

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

The tool has zero parameters, and schema description coverage is 100%. The description does not need to add parameter information beyond what the schema provides. Baseline for 0 parameters is 4, and the description meets that without trying to explain nonexistent parameters.

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 'Return a friendly Hello, world message' clearly states the tool's action (returning a message) and its output (a greeting). It is specific and distinct from the sibling tool 'add_numbers', which performs a different function.

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

Usage Guidelines3/5

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

No explicit guidance on when to use this tool versus alternatives is provided. However, given the simplicity and distinct purpose, usage is implied by the description. A higher score would require explicit when/when-not criteria.

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

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation5/5

The two tools have completely distinct purposes: one performs arithmetic addition, the other returns a greeting string. There is no overlap or potential for confusion.

Naming Consistency5/5

Both tool names follow a consistent verb_noun pattern (add_numbers, hello_world) using snake_case, which is clear and predictable.

Tool Count3/5

With only 2 tools, the server feels minimal. For a workshop or demo context this may be acceptable, but it is just at the low end of what would be considered well-scoped.

Completeness2/5

The tool surface is very limited. For a workshop server, basic operations like subtraction or different types of messages are missing, leaving obvious gaps for even simple tasks.

Maintenance

ActivitySlowing
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

  • mcpscope

    sla10132000
    F
    license
    A
    quality
    D
    maintenance
    A simple local MCP server that provides greeting and integer addition tools.
    2

  • Demo Server

    ruslanmv
    F
    license
    Not graded
    quality
    D
    maintenance
    A simple MCP server that exposes a calculator tool (addition) and a dynamic greeting resource.
    16

  • MCP Server Basic Example

    Aryansingh-ai
    A
    license
    Not graded
    quality
    C
    maintenance
    A basic MCP server that provides arithmetic tools (add, subtract) and a greeting resource, demonstrating core MCP concepts.
    GPL 3.0

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/RossTarrant/mcp-workshop'

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