Building an MCP Agent for Developer Journaling – The CodeScribe Example

What is the Model Context Protocol (MCP)?

The Model Context Protocol (MCP) is an open standard (originated by Anthropic) that allows large language models (LLMs) to interact with external tools and services through a unified, standardized interface. In essence, MCP defines a common protocol so that AI agents (like ChatGPT or Claude) can call functions, APIs, or operations outside their own model environment in a safe and structured way. This is extremely important because it turns a static AI model into an interactive agent – one that can perform tasks like retrieving data, executing code, or, as we’ll see, logging developer notes.

MCP can be thought of as the “glue” between an AI and the outside world. One official description likens MCP to what HTTP did for the web – a universal communication layer for tools. “MCP is best understood as a protocol for connecting AI agents to a wide range of external tools and services in a consistent way, much like how HTTP standardized communication for the web.” In practical terms, any AI client (for example, an AI coding assistant in VS Code or a chatbot like Claude) can invoke any MCP-compliant tool server, and they will “just work” together.

Why is MCP important? It provides several key benefits for AI integration:

• Standardization: MCP offers a structured, common way to plug in tools, so developers don’t have to write custom integration code for each AI or each tool. If your tool speaks MCP, any MCP-enabled AI can use it.
• Flexibility: It allows easy switching between different AI models or providers. You could use OpenAI’s models today and swap to another provider tomorrow with minimal changes.
• Security and Control: MCP typically runs locally or on your infrastructure. Your data (and actions like file writes) stay under your control, rather than being done directly by the AI in the cloud.
• Scalability: The protocol supports various communication channels (stdio, WebSockets, HTTP, etc.), making it suitable for different environments and scaling needs. It’s not tied to a single platform.

In short, MCP is quickly becoming a key enabler for “agentic” AI – AI systems that can perform multi-step tasks by invoking external tools. Major IDEs like Visual Studio Code have started adopting MCP to let AI-powered code assistants do more than just chat (for example, running build commands or querying databases). Anthropic open-sourced MCP in early 2024 and the industry has rallied behind it as a way to safely extend what AI assistants can do.

An Example MCP Agent: CodeScribe for Developer Journaling

To make this concrete, let’s look at CodeScribe, a simple yet powerful MCP agent that demonstrates how to build such tool-using AI agents. CodeScribe is an open-source project that serves as a developer journaling assistant. In essence, it lets a developer record notes and annotations during their coding workflow by simply telling an AI to “take a note,” and the agent will log it for them. Later, the agent can even summarize the notes or categorize them on request.

What does CodeScribe do? It’s described as “a lightweight journaling agent that logs developer notes to daily files using natural language prompts.” When running, CodeScribe listens for commands (either from an AI via MCP, or directly from the command line) and appends your notes to a text file for the current day. These journal files are stored in a folder (named .journal) with one file per date (e.g. `2025-06-08.txt for June 8, 2025), and each entry is timestamped in the format “[HH:MM:SS] message”. The idea is to integrate seamlessly with a developer’s workflow – you could be coding in VS Code, tell your AI assistant “note that I updated the authentication logic,” and the agent will record that in your journal.

Importantly, CodeScribe was built to showcase how to implement an MCP server in two languages (JavaScript and Python). It includes both deterministic tools (that perform a fixed logic without AI) and AI-powered tools (that call an LLM for help). We’ll focus on the Python version of CodeScribe here, which uses the OpenAI API (so you’ll need an OpenAI key) and the official MCP Python SDK. Using OpenAI’s GPT models for some features allows the agent to do more advanced things like summarization of notes, which we’ll get to soon.

Why journaling? If you’ve never kept a developer’s journal, it’s a great habit to start. A dev journal is a place to track what you’re doing and why – logging your thought process, approaches tried, and decisions made. This can save you time and headaches later. CodeScribe helps automate that habit by making it as easy as telling your AI, “Jot down that I fixed the user login bug.” The importance of such note-keeping is well known: “A developer’s journal is a tool to track what you’re doing and why... keeping a journal will save you tons of time and prevent many headaches as you work.” In short, CodeScribe is a handy example of an MCP agent that provides a very practical utility for developers.

Setting Up CodeScribe (Installation & Configuration)

Getting started with CodeScribe is straightforward. The code is available on GitHub (open-source), and you can install the Python agent with a few steps:

1. Clone the repository and install the Python package. For example, using pip in editable mode: pip install -e . (run this in the cloned codescribe repo directory). This will install any required dependencies, including OpenAI’s SDK and the MCP Python SDK that CodeScribe uses.

1. Provide your OpenAI API key. The summarization and categorization features rely on OpenAI’s GPT models, so the agent needs your API key to call the OpenAI API. You can supply this by creating a simple .env file in the project folder with a line like OPENAI_API_KEY=your_key_here. Alternatively, you can set an environment variable OPENAI_API_KEY in your shell before running the agent. Either way, make sure the key is configured; otherwise the AI-powered tools won’t function.

1. (Optional) VS Code Integration. If you plan to use CodeScribe with Visual Studio Code’s AI agent chat, you should add an entry to VS Code’s MCP configuration so it knows about CodeScribe. VS Code (in development mode or with Agent Mode enabled) looks for a .vscode/mcp.json file. In that JSON, you can register CodeScribe as a local server. For example, to use the Python implementation, you’d add something like:

{
    "servers": {
        "codescribe": {
            "type": "stdio",
            "command": "uv", 
            "args": ["run", "--directory", "${workspaceFolder}", "${workspaceFolder}/codescribe-agent.py", "mcp"]
        }
    }
}        

This tells VS Code to launch the codescribe-agent.py mcp server (using the uv runner) when the AI agent needs it. With this in place, your Copilot or Claude in VS Code can call on CodeScribe whenever you prompt it to take notes or summarize. (If you’re not using VS Code, you can ignore this – you can still run CodeScribe standalone as we’ll do next.)

Running and Testing CodeScribe from the Command Line

Before integrating with any AI, CodeScribe’s functionality can be tested directly via its command-line interface. In fact, the Python version provides a convenient CLI for each tool, so you can try out logging and querying your journal without going through an AI middleman. This is great for understanding how the agent works.

To start the MCP server (so it can listen for AI tool calls), you would run in a terminal:

python codescribe-agent.py mcp

This will start the CodeScribe agent, listening on standard input/output for MCP requests. In this mode, it waits for an AI client to send a JSON RPC (for example, a callTool request). However, if you just want to play with CodeScribe yourself, you can directly invoke its tools via the CLI without needing an AI client in the loop. Here are the primary commands you can use:

Log a note: python codescribe-agent.py log "Fixed a bug in the user authentication flow"

This will immediately append the given text (after the log command) into today’s journal file. For example, if today is 2025-06-08, it will write to .journal/2025-06-08.txt. Inside that file, you’d see a new line like [21:18:34] Fixed a bug in the user authentication flow (with the actual current time). The agent will also print a confirmation message to the console indicating the note was logged. This basic logging action is a deterministic tool – it doesn’t use any AI at all. It simply writes the text to a file, which is fast and reliable. (It’s called via MCP as a “tool”, but under the hood it’s just some Python file I/O.) Keep in mind that if the .journal directory doesn’t exist yet, CodeScribe will create it on the fly.

Summarize the journal: python codescribe-agent.py summarize

This command will fetch all entries you’ve logged for today (by reading the current date’s file in .journal) and generate a summary of those notes. The summary is produced by an OpenAI model (in this case, the gpt-4.1-mini model which provides a good balance between power and lower cost), so this is an AI-powered tool. The agent will send the journal text to the OpenAI API (using your API key) and ask for a concise summary of the day’s notes, then print the summary to your console. For example, if your notes were about fixing auth and updating the UI, the summary might say: “Today’s journal: fixed a user authentication bug and made UI enhancements to the dashboard.” The ability to summarize can be handy to get a quick recap of what you’ve done, especially if you log many entries in a day. (If you want to summarize a specific day other than today, you can provide a date argument, e.g. python codescribe-agent.py summarize 2024-05-01 to summarize May 1, 2024.)

Categorize (tag) journal entries: python codescribe-agent.py tag 2025-06-08

The “tag” command is another AI-driven function – it analyzes the journal entries for the specified date (here we used 2025-06-08 as an example) and categorizes them into topics or labels. Essentially, the agent asks the LLM to perform a classification on each note or on the set of notes. For instance, if one entry says “Fixed a bug in user auth” and another says “Brainstormed UI redesign ideas,” the agent might classify the first as Bug Fix and the second as Planning/Design. It will output the entries along with their categories, or a list of categories found in that day’s notes. This gives you a structured view of how you spent your time (e.g. X% of notes were about bugs, Y% about new features, etc.). Under the hood, CodeScribe’s implementation prompts the OpenAI model with something like: “Categorize the following journal entries into themes or tags.” Because it’s using the LLM, you can expect the results to be intelligent (it understands the content of the notes) but not always perfect. The term “tag” in the command is apt: it’s essentially tagging each note with keywords or categories. (In the repository README, this is described as “categorize entries”.)

All the above commands execute immediately on the local machine. Even though two of them use AI behind the scenes, they do so by calling the OpenAI API and then returning the results to you. You don’t need to be chatting with an AI to use these features – think of the CLI as a direct control panel to your agent.

A note on the non-AI vs AI tools: CodeScribe was intentionally built to showcase both. The logging tool is intentionally kept simple (no AI needed to just record text), which is great because it’s fast and doesn’t consume any API credits. The summarize and tag tools leverage the power of an LLM (GPT) to extract more insight from your notes. This separation also demonstrates a best practice: use deterministic logic where you can, and only use the AI when you need some intelligence or language understanding. In our case, writing a file is straightforward code, while summarizing or categorizing free-form text is exactly what GPT models are great at.

How CodeScribe Works Under the Hood

Now that we’ve seen it in action, let’s briefly discuss the internal design of the CodeScribe agent. This will help you understand how to create your own MCP agent in general.

At a high level, CodeScribe’s Python implementation is a single script (codescribe-agent.py) that defines a few tools and then runs an MCP server loop. Each tool corresponds to one of the actions we discussed (log, summarize, tag). When we run codescribe-agent.py mcp, it launches an MCP server that listens on STDIN for incoming JSON-RPC requests from an AI client. When an AI (client) wants to use a tool, it sends a callTool request with the tool’s name and any parameters. The CodeScribe agent receives that, finds the corresponding function, executes it, and sends back the result.

Internally, you can imagine the code looking something like this (pseudo-code simplified for illustration):

# Define the tools

def tool_log(message: str) -> str:

    # append message to .journal file

    ...

    return "Note logged."

def tool_summarize(date: str = today) -> str:

    # read the journal file for the date

    # call OpenAI API to summarize the content

    ...

    return summary_text

def tool_tag(date: str) -> str:

    # read the journal entries for the date

    # call OpenAI API to categorize/tag the entries

    ...

    return formatted_categories        

These functions are then registered with the MCP framework (the MCP Python SDK provides a decorator to which you register tool handlers). The agent then waits for requests. For example, if the AI sends a JSON like {"action": "callTool", "tool": "log", "params": {"text": "Fix auth bug"}}, the MCP server will invoke tool_log("Fix auth bug") in the CodeScribe code, then wrap the return value into a response back to the AI.

Because CodeScribe uses the official MCP SDK, a lot of heavy lifting is handled by the SDK: parsing the JSON, matching tool names, error handling, etc. As the developer, you mainly implement the tool logic. This is why building an MCP agent is relatively easy – you focus on what you want each action to do, and the SDK abstracts the protocol details.

For the log tool, the implementation uses basic file operations (open file, append text with timestamp). For the summarize and tag tools, the implementation uses the OpenAI Python library to call the OpenAI API. The OpenAI API call looks like: “Given these journal entries, produce a summary.” or “Classify these entries into categories.” behind the scenes. The results come back as plain text, which the agent then returns up to the AI client or CLI. The use of the OpenAI API is configurable via the OPENAI_API_KEY we set – you could swap in a different LLM by changing the API and prompts, but OpenAI was used in this example for convenience.

The key takeaway here is that the MCP agent acts as a middleman: it translates high-level requests (like “summarize my notes”) into concrete actions (reading a file, calling an API) and gives the result back. The AI client (like VS Code’s Copilot Agent) doesn’t need to know how CodeScribe does its job, just that if it asks CodeScribe to summarize, it will get a summary text in return. This separation of concerns is exactly what MCP enables.

To visualize an end-to-end interaction: imagine you have VS Code’s AI chat open, and you type: “Hey Copilot, summarize my coding journal for today.” The AI (maybe GPT-4) processes your request and decides that to answer you, it should use an external tool (because it recognizes the term “journal” and knows it has CodeScribe available). Via MCP, it sends a callTool for summarize to the CodeScribe server. CodeScribe’s tool_summarize reads .journal/2025-06-08.txt, calls OpenAI API to summarize it, and sends back a short summary. The AI client receives that and then presents it to you in the chat: “Today you worked on user authentication bug fixes and UI redesign planning.” All of this happens within a second or two. From your perspective, the AI assistant magically knew what you worked on – but under the hood it was CodeScribe doing the heavy lifting as an MCP agent.

Building an MCP Agent Quickly with Vibe Coding

You might be wondering, how difficult is it to create something like CodeScribe from scratch? The surprising answer these days is: not very difficult at all, thanks to AI-assisted development. In fact, CodeScribe itself was developed in large part using AI coding assistants (OpenAI’s Codex/GPT models, and GitHub Copilot). This approach is part of a new trend known as “vibe coding.”

Vibe coding refers to a style of coding where you describe what you want in natural language, and let the AI generate the code for you (you then refine or adjust as needed). As one description puts it: “Vibe coding is about building software without worrying about syntax. Instead of manually writing code, users describe what they want in everyday language, and AI generates the required code.” The term was famously coined by AI researcher Andrej Karpathy, who suggested that you can “write software by simply expressing what you want in plain English while AI takes care of the actual code”. In practice, this often means using tools like GitHub Copilot or IDEs like Cursor AI – you type instructions or comments, and the AI writes most of the code for you. You essentially trust the AI to do the bulk of coding, only guiding it with high-level prompts (hence “follow the vibes” of the AI’s output).

For CodeScribe, the developer followed a vibe coding approach. For example, they might have written a comment like “# TODO: Implement a function to write a note to a daily journal file” and accepted Copilot’s suggestion for how to do it, or asked an AI in ChatGPT “How do I append a timestamped line to a text file in Python?” to get a code snippet. By iterating prompt by prompt, one can build the entire agent rapidly. In fact, building MCP servers is a popular demo for vibe coding precisely because it’s so quick to get something working. One recent guide showed how to create a fully functional MCP server in just five prompts using an AI pair-programming tool. The AI handled everything from setting up the project structure to writing the code for tool functions and even integrating with an API, all with minimal human keystrokes. This goes to show that with modern AI help, a prototype like CodeScribe can be built in a matter of hours, not days.

In CodeScribe’s case, the combination of OpenAI’s Codex models and GitHub Copilot generated most of the code with the developer validating the outputs. This is a powerful workflow: you focus on what you want (e.g., “I need an MCP tool that summarizes text using the OpenAI API”) and the AI figures out how to implement it in code. The result is a big boost in productivity. Of course, one must still review and test the code (AI isn’t perfect), but as a mid-level developer you can leverage your knowledge to correct any mistakes the AI makes. The heavy lifting of boilerplate, API calls, and even complex logic can often be offloaded to the AI.

In summary, vibe coding made it possible to create a useful agent like CodeScribe in very little time. This means that you too can rapidly develop your own MCP agents to automate tasks or integrate tools with AI. Whether it’s a journaling bot, a PR reviewer, or a data-fetching assistant, the pattern is similar: define what you need, let AI assist in writing it, and use MCP to connect it to your AI of choice.

Conclusion

We started by explaining the Model Context Protocol (MCP) and why it’s becoming an important standard for empowering AI with tools. With MCP, even a simple idea – like a developer’s journal – can be turned into an AI-accessible service. The CodeScribe example illustrated how to build a minimal MCP agent that logs notes, and also how to enhance it with AI capabilities (summarization and categorization using OpenAI’s models). We walked through how to set up and try CodeScribe, and saw how each tool functioned from both the user’s and developer’s perspective.

The big takeaway is that creating an MCP agent is quite accessible. You don’t need a massive engineering team or months of work. By using the MCP SDK and modern AI coding tools, a single developer can spin up a custom agent in a short time. CodeScribe demonstrates that in a few hundred lines of code (most of which an AI can generate), you get a genuinely useful tool that enhances your workflow. It’s a testament to how far developer tooling has come: we’re now writing programs with the help of AI for AI to use in turn!

If you’re inspired by this, you can find CodeScribe on GitHub and use it as a template or starting point for your own MCP agent. Try thinking of repetitive or assistive tasks in your daily work – could an AI agent handle those for you if it had the right tool? Chances are, with MCP and a bit of “vibe coding” magic, you can build that agent in an afternoon. Happy coding, and enjoy the productivity boost of having your very own AI tools at your command!