index

Introduction

AI, multi-agent systems, RAGs, MCPs, etc. You can’t open twitter without seeing any of these buzzwords anymore. You would be correct to be skeptical about the hype, I was too. But I just realized that there just hasn’t been many good implementations and uses of these technologies.

Every other startup is selling Automated Redteaming, AI Powered Penetration Testing, or an AI that can outperform human experts.. Etc.

Having personally demoed a lot of these products, I can say that most of them are not what they’re portraying themselves to be. Half of these did not even have AI involved in the product, it was just scheduled tasks and workflows.

One tool that changed my mind was ida-pro-mcp / GhidraMCP, which allows LLMs to directly interact with IDA Pro and Ghidra to perform tasks such as:

Disassembling functions
Listing functions
Renaming functions
Renaming variables
Adding comments

I tried to use these MCPs to solve a Flare-On challenge I had already solved and prompted the LLM to try and solve the challenge, to see if it could help me solve it faster. It was able to solve the challenge by itself within 5 minutes.. I was blown away.

I have been using it since then with any binary I try to analyze, to help me understand the binary and rename functions/variables faster. It is a game-changer.

This will be the first introductory post focusing on MCP servers, and how to set them up for AI agents use. Will focus on building a simple Kimai MCP server in this post to introduce the concept.

This post will be very basic and is mostly to force myself to start writing. I plan to write a series of blog posts about the use of AI in cybersecurity with a focus on the offensive side. The next posts will be more advanced and will cover:

Using Pydantic models/fields to constrain the data passed to the tools and reduce errors
Creating an MCP server for BruteRatel to interact with the C2 server and perform tasks
The use of local LLMs and how to use cloud LLMs with sanitized data
Improving the knowledge-base of the LLM by providing it with a RAG pipeline
Creating and designing a multi-agent system with an orchestrator agent to perform offensive operations

What is an MCP server?

If you’ve used ChatGPT, you’ve probably seen it use tools when you ask it to do something that’s beyond its knowledge cutoff or when it needs to run code.

if you ask ChatGPT to get the result of (5 ** 15) % 51, it will return a wrong answer if it does not use a tool to calculate the result.

If you explicitly ask it to calculate the result using python, it will use the python tool to calculate the correct result.

ChatGPT using tools

Another tool is Web Search, which allows ChatGPT to search the web for current information beyond its knowledge cutoff, making it much more useful and up to date.

These tools are internal tools that are not exposed to the user and are not customizable.

MCP stands for “Model Context Protocol”. It is a protocol that allows you to extend the capabilities of AI agents by providing them with custom tools. These tools will transform the way you use LLMs from using them as a simple chatbot and copy-paste source, to using them as a powerful assistant that can perform tasks and make changes to your environment.

MCP Server Architecture

There are many ways to create an MCP server, but the most common way is to use the gofastmcp library, which we will be using in this post.

Protocol

The protocol involves three parts:

An LLM model that can be used to generate text, can host multiple clients to interact with different MCP servers
A client that can be used to interact with the server
A server that exposes tools, context and prompts to clients

Transport

Transports are the way the client and server communicate with each other.

The most common transports are:

stdio for in-process communication
Streamable HTTP
Custom transports

Core Components

An MCP server can expose the following components:

Tools: Functions that the server can use to perform tasks
Resources: Read-only data that the server can use to perform tasks
Prompts: Prompts that the server can use for specific tasks
Context: Context updates to the client for logging, progress reporting, metadata, etc.

Tools

Tools simply put are just python functions that are exposed to the client to use.

The LLM will have access to the tool’s name, description and argument types.

@mcp.tool
def add(a: int, b: int) -> int:
  """Adds two integer numbers together."""
  return a + b

Resources

Resources provide read-only access to data for the LLM or client application.

@mcp.resource("data://config")
def get_config() -> dict:
  """Provides application configuration as JSON."""
  return {
    "theme": "dark",
    "version": "1.2.0",
    "features": ["tools", "resources"],
  }

Resources templates are a way to create resources that are dynamically generated by the server based on the client’s supplied parameters.

@mcp.resource("weather://{city}/current")
def get_weather(city: str) -> dict:
  """Provides weather information for a specific city."""
  return {
      "city": city.capitalize(),
      "temperature": 22,
      "condition": "Sunny",
      "unit": "celsius"
  }

Prompts

Prompts are a way to provide templated messages to the client, and they can be dynamically generated based on the user’s input.

@mcp.prompt
def ask_about_topic(topic: str) -> str:
  """Generates a user message asking for an explanation of a topic."""
  return f"Can you please explain the concept of '{topic}'?"

KimaiMCP

Kimai is an opensource time tracking tool that can be used to track time and create timesheets.

Kimai Dashboard

To add a new time entry, you have to login, navigate to the time tracking page, and click on the Create button and fill the ordeous form.

Kimai Create Time Entry

While this is not a very complex task, it is still a tedious process that you have to do daily (or if you’re like me, spend 15—30 minutes every couple weeks to catch up). Most of the time is spent on remembering what I was doing a week ago, and filling the form with the correct time.

We can build a simple MCP server that can be used to have the AI agent create and manage our timesheets by just asking it to do so in natural language.

Setting up the MCP server

We will be using the gofastmcp library to create the MCP server.

Start with the following directory structure:

kimai-mcp/
 └──      kimaiapi/
 │  ├────      client.py
 │  ├────      config.py
 │  └────      __init__.py
 ├──      .env
 ├──      main.py
 ├──      pyproject.toml
 └──      uv.lock

Create a .env with the Kimai API key

1
KIMAI_BASE_URL=https://demo-stable.kimai.org
2
KIMAI_API_TOKEN=ec6204ae103ea0768b2ab44a7
3

4
# Optional
5
KIMAI_USER_ID=
6
KIMAI_TIMEOUT=30

1
import os
2
from pydantic import BaseModel
3
from dotenv import load_dotenv
4

5
load_dotenv()
6

7
class KimaiConfig(BaseModel):
8
    """Configuration for Kimai API client."""
9
    base_url: str
13 collapsed lines
10
    api_token: str
11
    timeout: int = 30
12

13
    @classmethod
14
    def from_env(cls) -> "KimaiConfig":
15
        """Create a KimaiConfig instance from environment variables."""
16
        return cls(
17
            base_url=os.getenv("KIMAI_BASE_URL", ""),
18
            api_token=os.getenv("KIMAI_API_TOKEN", ""),
19
            timeout=int(os.getenv("KIMAI_TIMEOUT", "30")),
20
        )
21

22

23
def get_config() -> KimaiConfig:
24
    """Retrieve the Kimai configuration from environment variables."""
8 collapsed lines
25
    config = KimaiConfig.from_env()
26

27
    if not config.base_url:
28
        raise ValueError("KIMAI_BASE_URL environment variable is required")
29
    if not config.api_token:
30
        raise ValueError("KIMAI_API_TOKEN environment variable is required")
31

32
    return config

To simplify managing the dependencies, we will be using uv

[project]
name = "kimai-mcp"
version = "0.1.0"
description = "An MCP server for interacting with Kimai"
authors = [{name = "YourName", email = "yourname@example.com"}]
requires-python = ">=3.13"
dependencies = [
  "ruff==0.12.1",
  "fastmcp==2.9.2",
  "pydantic==2.11.7",
  "requests==2.32.4",
]

[project.scripts]
kimai-mcp = "main:app"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.ruff]
line-length = 120

[tool.hatch.metadata]
allow-direct-references = true

[tool.hatch.build.targets.wheel]
include = [
    "main.py",
    "kimaiapi",
]

1
from fastmcp import FastMCP
2

3
mcp = FastMCP("Kimai MCP")
4

5
@mcp.tool
6
def hello(name: str) -> str:
7
  """Returns a greeting message."""
8
  return f"Hello, {name}!"
9

10
mcp.run(
11
  transport="http",
12
  host="127.0.0.1",
13
  port=4200,
14
  log_level="debug",
15
  path="/mcp",
16
)

To install the dependencies and run the server, run the following commands:

uv venv
source .venv/bin/activate
uv sync
uv run kimai-mcp

We can add the MCP server to use with Claude CLI or any other MCP client.

claude mcp add --transport http kimai-mcp http://localhost:4200/mcp

Claude CLI MCP Server

Claude will now automatically use the MCP tools when it needs to.

Claude Uses MCP Tools

Creating Tools For Kimai

Now we get to the fun part, creating tools to interact with Kimai.

As a normal user, there are only a few functions that I really care about:

Creating new time entries
Deleting time entries

To create a new timesheet entry, we need to provide the following:

date
start time
duration
project
activity
and optionally a description

According to the Kimai API documentation, we can create a new time entry with the following JSON POST to /api/timesheets:

1
{
2

3
  "begin": "2019-08-24T14:15:22Z",
4
  "end": "2019-08-24T14:15:22Z",
5
  "project": 0,
6
  "activity": 0,
7
  "description": "string",
8
  "fixedRate": 0,
9
  "hourlyRate": 0,
10
  "user": 1,
11
  "tags": "string",
12
  "exported": True,
13
  "billable": True
14
}

Similarly, a GET to /api/timesheets will return a list of timesheet entries.

1
[
2
  {
3
    "activity": 0,
4
    "project": 0,
5
    "user": 0,
6
    "tags": [
7
      "string"
8
    ],
9
    "id": 0,
10
    "begin": "2019-08-24T14:15:22Z",
11
    "end": "2019-08-24T14:15:22Z",
12
    "duration": 0,
13
    "description": "string",
14
    "rate": 0,
15
    "internalRate": 0,
16
    "exported": false,
17
    "billable": true,
18
    "metaFields": [
19
      {
20
        "name": "string",
21
        "value": "string"
22
      }
23
    ]
24
  }
25
]

An optional paramater is full=True to get the full details of the timesheet entry, saving us from having to make additional API calls to get the full details on the project and activity.

1
  {
2
    "tags": [],
3
    "id": 435,
4
    "begin": "2025-07-11T03:42:00-0700",
5
    "end": "2025-07-11T12:59:00-0700",
6
    "duration": 33420,
7
    "user": {
9 collapsed lines
8
      "apiToken": true,
9
      "initials": "JD",
10
      "id": 1,
11
      "alias": "John Doe",
12
      "title": "Developer",
13
      "username": "john_user",
14
      "accountNumber": null,
15
      "enabled": true,
16
      "color": null
17
    },
18
    "activity": {
26 collapsed lines
19
      "id": 1154,
20
      "project": {
21
        "id": 97,
22
        "customer": {
23
          "id": 6,
24
          "name": "Donnelly, McGlynn and Botsford",
25
          "number": "C-51678203",
26
          "comment": "Et harum ipsum nihil aut. Pariatur doloremque hic aut eius.",
27
          "visible": true,
28
          "billable": true,
29
          "color": null
30
        },
31
        "name": "Qui similique",
32
        "comment": "Quis eligendi atque consequatur corrupti exercitationem quibusdam. Dolore repellendus minus est perspiciatis omnis labore. Enim sint earum minus et nostrum tempore totam.",
33
        "visible": true,
34
        "billable": true,
35
        "globalActivities": true,
36
        "number": null,
37
        "color": null
38
      },
39
      "name": "Sit nam",
40
      "comment": "Non explicabo unde dolores assumenda corrupti magnam. Esse soluta iusto impedit. Sunt doloribus impedit dicta ut. Eligendi quos nesciunt dolorum aut maiores culpa aliquid.",
41
      "visible": true,
42
      "billable": true,
43
      "number": null,
44
      "color": null
45
    },
46
    "project": {
17 collapsed lines
47
      "id": 97,
48
      "customer": {
49
        "id": 6,
50
        "name": "Donnelly, McGlynn and Botsford",
51
        "number": "C-51678203",
52
        "comment": "Et harum ipsum nihil aut. Pariatur doloremque hic aut eius.",
53
        "visible": true,
54
        "billable": true,
55
        "color": null
56
      },
57
      "name": "Qui similique",
58
      "comment": "Quis eligendi atque consequatur corrupti exercitationem quibusdam. Dolore repellendus minus est perspiciatis omnis labore. Enim sint earum minus et nostrum tempore totam.",
59
      "visible": true,
60
      "billable": true,
61
      "globalActivities": true,
62
      "number": null,
63
      "color": null
64
    },
65
    "description": "Poor Alice! It was so much about a foot high.",
66
    "rate": 603.4167,
67
    "internalRate": 603.4167,
68
    "exported": false,
69
    "billable": true,
70
    "metaFields": []
71
  },

get_projects, get_activities, get_timesheets

We can provide the list of activities and projects to the client through tools.

10
  def get_activities(self, query_parameters=None) -> list[dict]:
11
    url = f"{self.base_url}/api/activities"
12
    response = self._make_request("GET", url, params=query_parameters)
13
    return response.json()
14

15
  def get_projects(self, query_parameters=None) -> list[dict]:
16
    url = f"{self.base_url}/api/projects"
17
    response = self._make_request("GET", url, params=query_parameters)
18
    return response.json()

1
from pydantic import Json
2
from kimaiapi.client import KimaiAPI
3
from kimaiapi.config import get_config
4
from fastmcp import FastMCP
5

6
config = get_config()
7
kimai_api = KimaiAPI(
8
  base_url=config.base_url,
9
  api_token=config.api_token,
10
)
11

12
mcp = FastMCP("Kimai MCP")
13

14
@mcp.tool()
15
async def get_projects() -> Json:
16
  """Returns a list of projects on Kimai."""
17
  projects = kimai_api.get_projects()
18
  return projects
19

20
@mcp.tool()
21
async def get_activities() -> Json:
22
  """Returns a list of activities on Kimai."""
23
  activities = kimai_api.get_activities()
24
  return activities
25

26
mcp.run(
27
  transport="http",
28
  host="127.0.0.1",
29
  port=4200,
30
  log_level="debug",
31
  path="/mcp",
32
)

Claude is now able to use the get_activities and get_projects tools to get the list of projects and activities.

Claude Uses MCP Tools

Claude List Projects

Note

While the above code works, it is better to provide the LLM with only the relevant data to avoid overwhelming it with too much information.

Explanation

14
@mcp.tool()
15
async def get_projects() -> Json:
16
  """Returns a list of projects on Kimai."""
17
  projects:Json = kimai_api.get_projects()
18
  filtered_projects:Json = [{"id": project["id"], "name": project["name"]} for project in projects]
19
  return filtered_projects
20
  return projects
21

22
@mcp.tool()
23
async def get_activities() -> Json:
24
  """Returns a list of activities on Kimai."""
25
  activities:Json = kimai_api.get_activities()
26
  filtered_activities:Json = [
27
    {
28
      "id": int(activity["id"]),
29
      "name": activity["name"],
30
      "parentTitle": activity.get("parentTitle", ""),
31
      "project": int(activity.get("project")) if activity.get("project") else None,
32
    }
33
    for activity in activities
34
  ]
35
  # sort activities by project name and then by activity project id
36
  filtered_activities.sort(key=lambda x: (x["project"] or 0, x["id"]))
37
  return filtered_activities
38
  return activities

We reduced the number of lines from 3430 to 988. (even more if you count by tokens saved) Optimized Code

Now for get_timesheets(), we can either use GET to /api/timesheets with optional filters for begin, end, project, size or GET to /api/timesheets/recent with optional filters for size and begin.

It is important to not treat MCP tools as a simple API wrapper where we entrust the LLM to call the API with the raw JSON data. The more you constrain the LLM, the more you get it to return the correct data.

45
  def get_timesheets(self, filters=None):
46
    url = f"{self.base_url}/api/timesheets"
47
    response = self._make_request("GET", url, params=filters)
48
    return response.json()

38
@mcp.tool()
39
async def get_timesheets(
40
  begin: str = '',
41
  end: str = '',
42
  activity: int = 0,
43
  project: int = 0,
44
  size: int = 20,
45
) -> Json:
46
  """
47
  Returns a list of timesheets on Kimai.
48
  Parameters:
49
    - begin: Start date in HTML5 datetime-local (e.g., 'YYYY-MM-DDThh:mm:ss').
50
    - end: End date in HTML5 datetime-local (e.g., 'YYYY-MM-DDThh:mm:ss').
51
    - activity: Activity ID to filter by.
52
    - project: Project ID to filter by.
53
    - size: Number of timesheets to return (default is 20).
54
  Note: If 'begin' and 'end' are not provided, all timesheets will be returned.
55
  If 'activity' and 'project' are not provided, no filtering will be applied.
56
  If 'size' is not provided, it defaults to 20.
57
  """
58
  filters = {
59
    "begin": begin,
60
    "end": end,
61
    "activity": activity or None,
62
    "project": project or None,
63
    "size": size,
64
    "full": "true"
65
  }
66
  timesheets:Json = kimai_api.get_timesheets(filters)
67
  filtered_timesheets:Json = [
68
    {
69
      "id": int(timesheet["id"]),
70
      "begin": timesheet["begin"],
71
      "end": timesheet["end"],
72
      "duration": timesheet["duration"],
73
      "activity-id": int(timesheet["activity"]["id"]) if timesheet.get("activity") else None,
74
      "activity-name": timesheet["activity"]["name"] if timesheet.get("activity") else "",
75
      "project-id": int(timesheet["project"]["id"]) if timesheet.get("project") else None,
76
      "project-name": timesheet["project"]["name"] if timesheet.get("project") else "",
77
      "description": timesheet.get("description", ""),
78
    }
79
    for timesheet in timesheets
80
  ]
81
  return filtered_timesheets

The function’s docstring is important to provide the LLM with the correct context of the tool. Let’s see it in action.

MCP Get Timesheets

get_todays_date

What if we try something more complex on a new Claude session?

give me all timesheet entries from May till the end of June for the project Necessitatibus et

MCP Get Timesheets Project

Almost.. but it got the year wrong because of its knowledge cutoff. Let’s create a tool to provide the LLM with today’s date.

1
from datetime import datetime
2

3
...
4

5
@mcp.tool()
6
async def get_todays_date() -> str:
7
  """Returns today's date in HTML5 datetime-local format."""
8
  return datetime.now().strftime("%Y-%m-%dT%H:%M:%S")

Rerunning the same query on a new Claude session, we get the result we expect as it first calls the get_todays_date tool to get the current date.

MCP Get Timesheets Project With Date Tool

create_timesheet, delete_timesheet

With the informational tools ready, we can now make some changes to the timesheet.

45
def create_timesheet(self, timesheet_data) -> Json:
46
  url = f"{self.base_url}/api/timesheets"
47
  response = self._make_request("POST", url, json=timesheet_data)
48
  return response.status_code == 200  # Created successfully
49

50
def delete_timesheet(self, id) -> bool:
51
  url = f"{self.base_url}/api/timesheets/{id}"
52
  response = self._make_request("DELETE", url)
53
  return response.status_code == 204  # No Content

89
@mcp.tool()
90
async def delete_timesheet(id: int) -> str:
91
  """
92
  Deletes a timesheet by ID.
93
  Parameters:
94
    - id: The ID of the timesheet to delete.
95
  Returns a confirmation message.
96
  """
97
  status = kimai_api.delete_timesheet(id)
98
  if status:
99
    return f"Timesheet with ID {id} deleted successfully."
100
  else:
101
    return f"Failed to delete timesheet with ID {id}"
102

103
@mcp.tool()
104
async def create_timesheet(
105
  begin: str,
106
  end: str,
107
  activity_id: int,
108
  project_id: int,
109
  description: str = "",
110
) -> Json:
111
  """
112
  Creates a new timesheet.
113
  Parameters:
114
    - begin: Start date in HTML5 datetime-local (e.g., 'YYYY-MM-DDThh:mm:ss').
115
    - end: End date in HTML5 datetime-local (e.g., 'YYYY-MM-DDThh:mm:ss').
116
    - activity_id: Activity ID for the timesheet.
117
    - project_id: Project ID for the timesheet.
118
    - description: Optional description for the timesheet.
119
  Returns the created timesheet as JSON.
120
  """
121
  timesheet_data = {
122
    "begin": begin,
123
    "end": end,
124
    "activity": activity_id,
125
    "project": project_id,
126
    "description": description,
127
  }
128
  return kimai_api.create_timesheet(timesheet_data)

Testing the MCP Server

I started a new Claude session and asked it the following:

what was I working on these past 7 days?

MCP Get Timesheets Past 7 Days

delete my entries on the Dolorum a project on june 22, it is created by mistake

MCP Delete Timesheet

Note

I decided to mention what day is it today because I forgot to add that information to the get_todays_date() tool.

so I did the same work i did on june 29 on June 28, and delete all of my entries from July 1
onwards. Instead, I will be working on A animi on the Dolrem voluptate project, 8 hours a day starting 9AM of work week days and 5 hours starting 11am on weekends. do this from july 1 to july 10 (It’s Sunday today 29th of June)

Delete July and Create New Timesheet

It missed deleting a few timesheets for some reason, and it wasn’t able to create the new timesheet because I said Dolrem instead of Dolorem. I don’t expect this to be an issue when using real project and activity names instead of lorem ipsum.

there are still 4 entries remaining in July, delete them, and the project I want you to create is Dolorum a, doing Quia magnam

Create July Timesheet

It managed to perform the tasks successfully, including the different durations and starting hours for weekends.

Kimai July Timesheet

Conclusion

In this post, we scratched the surface of what LLMs powered with custom MCP tools can do with a very basic implementation.

There are many ways to improve MCP servers, such as:

Using a more powerful LLM (Though, I don’t think it’s necessary for this use case as I’ve been using local Qwen3:14b for creating timesheets for work)
Provide the LLM with a custom prompt for the task
Make use of Pydantic models/fields to validate the data and provide descriptions and examples for each argument passed to the tool
Make use of the MCP Context to provide status updates to the client (progress of delete/create operations)
In case of larger MCP servers, organize tools and resources into structured folders
Use Field() regex patterns to restrict the data passed to the tools

We will cover some of these in the upcoming posts.

Introduction to MCP Tools: KimaiMCP