DEV Community: Jefree Sujit

Who’s Really in Control? How AI Agents Decide What Happens Next

Jefree Sujit — Thu, 22 Jan 2026 07:38:19 +0000

When people talk about AI agents, the conversation usually jumps straight to tools, frameworks, or demos. But in real systems, the most important question isn’t what model you’re using — it’s how decisions are made and in what order actions happen.

Some systems follow a strict sequence.
Others are given a goal and decide the steps on their own.

Knowing this difference is the key to understanding How AI Agents Actually Work

This article is Part II of a three-part series on AI Agents.
In Part I, we explored what an AI agent is and how agents differ from simple prompts.
Here, we focus on how agents are structured and controlled — through workflows or autonomy. If you haven't checked it yet, here's the link

You can start with this article on its own, but it builds naturally on the ideas introduced earlier.

A Simple Analogy Before the Tech

Imagine two ways of getting dinner made.

In the first, you follow a recipe.
Every step is written down. You chop first, heat later, season at a specific moment, and cook for an exact duration. If you skip a step or change the order, the dish fails.

In the second, you hire a head chef.
You tell them what kind of dinner you want. They decide what dishes to make, in what order, what can be prepared in parallel, and when to adjust if something isn’t working.

Both approaches can produce great food.
But the control model is completely different.

That difference maps almost perfectly to how workflow agents and autonomous agents operate.

Before we get there, though, we need one foundational concept.

State Machines.

What Is a State Machine?

A state machine is a system that progresses through a series of well-defined states, one at a time, based on rules and transitions.

Each state represents a point in the process.
Each transition represents a condition that allows the system to move forward.

For example, lets take any authentication flow:

You cannot jump ahead.
You cannot reorder steps.
Every state depends on the previous one.

This model shows up everywhere in software: authentication flows, payment pipelines, order fulfillment, approvals, and booking systems. The reason is simple: many real-world processes depend on strict order.

Workflow agents are essentially state machines with intelligence embedded into each step.

A Quick Recap: What Is an AI Agent?

As we learnt from the previous article, an AI agent is something that can:

Perceive its environment (inputs, memory, context)
Decide what to do next (reasoning or logic)
Act using tools, APIs, or side effects

What changes between different kinds of agents is who controls the decision flow.

Is the sequence of actions decided upfront by the developer/orchestrator?
Or does the agent decide dynamically based on a goal?

That single difference gives us two major design patterns.

Orchestration-Centric Agents (Workflow Agents)

Workflow agents, also called orchestration-centric agents, operate inside a predefined structure. The flow of execution is known ahead of time.

You decide:

Which agents exist
The order in which they run
Whether steps run sequentially, in parallel, or in loops

The agent itself does not decide what comes next.
The workflow does.

This makes workflow agents highly predictable, easy to debug, and safe for critical systems.

When Workflow Agents Make Sense

Workflow agents work best when the process itself has strong dependencies.

Consider a travel booking assistant. You cannot plan hotels before knowing arrival times. You cannot arrange transport before the destination is finalized. Each step relies on the previous one being completed successfully.

This is not a creativity problem.
It’s a state transition problem.

Workflow agents are ideal when:

Order matters
Steps depend on earlier outputs
Reliability is more important than flexibility
You want full control over execution

Workflow Agents in Practice (Google ADK, TypeScript)

Here’s how a workflow agent looks using Google’s Agent Development Kit (ADK) in TypeScript.

import { LlmAgent, SequentialAgent, Runner } from "@google/adk";
import * as dotenv from "dotenv";

dotenv.config();

// Title agent — generates a blog title
const titleAgent = new LlmAgent({
  name: "TitleAgent",
  model: "gemini-2.5-flash",
  instruction: "Generate a catchy title for a blog post about AI agents.",
  outputKey: "title"
});

// Outline agent — creates an outline
const outlineAgent = new LlmAgent({
  name: "OutlineAgent",
  model: "gemini-2.5-flash",
  instruction: "Create a detailed outline for the blog post based on title.",
  outputKey: "outline"
});

// Content agent — writes content from outline
const contentAgent = new LlmAgent({
  name: "ContentAgent",
  model: "gemini-2.5-flash",
  instruction: "Write blog content following the given outline.",
  outputKey: "content"
});

// The workflow agent — runs sub-agents in sequence
const blogWorkflowAgent = new SequentialAgent({
  name: "BlogWorkflow",
  subAgents: [titleAgent, outlineAgent, contentAgent],
});

async function main() {
  const runner = new Runner({ agent: blogWorkflowAgent });

  const response = await runner.run({
    input: { topic: "Understanding Workflow vs Autonomous Agents" },
  });

  console.log("Workflow Result:", response.output);
}

main();

The important thing here is the controlled flow. The directions and next steps are previously defined. Although in some cases, we might have an conditional edge that takes to more than one agent, but the control is within the agent orchestrator.

That’s orchestration-centric design.

Autonomy-Centric Agents (Autonomous Agents)

Autonomous agents flip the model.

Instead of being told how to proceed, they are told what outcome to achieve. The agent then decides which actions to take, in what order, and whether to retry or adjust.

This is autonomy-centric design.

The agent becomes a coordinator. It may invoke sub-agents, route tasks dynamically, loop on failures, or stop early if the goal is met.

When Autonomous Agents Make Sense

Autonomous agents shine when the order of actions is flexible and the goal matters more than the path.

Take content creation as an example. Writing a blog does not require a strict sequence. You can generate a title, outline, images, and content in any order. Some tasks can happen in parallel. Some may need refinement.

This is not a state machine problem.
It’s a goal resolution problem.

Autonomous agents are well suited when:

Tasks can be done in any order
Parallel execution is beneficial
Exploration or creativity is involved
The agent needs to adapt mid-execution

Autonomous Agent Example (Google ADK, TypeScript)

Below is a more realistic autonomous setup using multiple agents coordinated by a parent controller.

Specialized Sub-Agents

import { LlmAgent } from "@google/adk";

export const titleAgent = new LlmAgent({
  name: "TitleAgent",
  model: "gemini-2.5-flash",
  instruction: "Generate a clear, catchy blog title.",
  outputKey: "title"
});

export const outlineAgent = new LlmAgent({
  name: "OutlineAgent",
  model: "gemini-2.5-flash",
  instruction: "Create a structured blog outline.",
  outputKey: "outline"
});

export const imageAgent = new LlmAgent({
  name: "CoverImageAgent",
  model: "gemini-2.5-flash",
  instruction: "Suggest cover image ideas.",
  outputKey: "images"
});

export const contentAgent = new LlmAgent({
  name: "ContentAgent",
  model: "gemini-2.5-flash",
  instruction: "Write the full blog content.",
  outputKey: "content"
});

export const reviewAgent = new LlmAgent({
  name: "ReviewAgent",
  model: "gemini-2.5-flash",
  instruction: "Review and suggest improvements.",
  outputKey: "review"
});

Parent (Controller) Agent

import {
  titleAgent,
  outlineAgent,
  imageAgent,
  contentAgent,
  reviewAgent
} from "./agents";

import { LlmAgent } from "@google/adk";

const autonomousBlogController = new LlmAgent({
  name: "AutonomousBlogController",
  model: "gemini-2.5-flash",
  instruction: `
You are a parent autonomous agent.

Goal:
Produce a complete blog package with a title, outline, images, content, and review.

Rules:
- Decide which agent to call next.
- Retry or refine outputs if needed.
- Order is not fixed.
- Stop only when the blog is complete and satisfactory.
`,
  tools: [
    titleAgent,
    outlineAgent,
    imageAgent,
    contentAgent,
    reviewAgent
  ],
  outputKey: "finalBlog"
});

await autonomousBlogController.execute({
  input: {
    topic: "Workflow Agents vs Autonomous Agents"
  }
});

Here, there is no predefined sequence. The agents are defined, but what needs to happen when is not controlled by the Orchestrator, but by the agent itself. The agent reasons about what to do next and adapts as it goes.

That’s autonomy.

Workflow vs Autonomous: A Clear Comparison

Here's a quick comparison between workflow and autonomous agents

Aspect	Workflow Agents	Autonomous Agents
Control flow	Predefined	Dynamic
Structure	State machine	Goal-driven
Order	Fixed	Decided at runtime
Parallelism	Explicit	Emergent
Best suited for	Pipelines, business flows	Creative, adaptive tasks
Debuggability	High	Moderate
Flexibility	Lower	Higher

Final Thoughts

Workflow agents and autonomous agents aren’t competing ideas. They’re different answers to different problems.

When order, safety, and predictability matter, workflows are the right tool.
When goals, adaptability, and delegation matter, autonomy shines.

Most real systems use both — autonomous agents at the top to decide what needs to be done, and workflow agents underneath to execute critical steps safely.

In the next article, we’ll zoom out even further and address a common source of confusion:

AI Agents vs Agentic AI — why they’re not the same thing, and why that distinction matters.

The Future of AI Agents Isn’t What You Think — Here’s What Actually Matters

Jefree Sujit — Tue, 23 Dec 2025 11:20:26 +0000

2025 is about to end. Just a couple of years back, AI was mostly about generating things — text, code, images. We played around with chatbots, translation tools, and creative AI art generators, and honestly, it already felt magical. But something subtle has been changing.

Models didn’t just respond anymore. They started doing more: write code, debug stuff, answer complex questions. Soon after, tool calling arrived. Suddenly, the model wasn’t just sitting inside the chat box anymore. It could reach out, use a calculator, hit an API, browse the web. The conversation is no longer only about what AI can create on the spot. It’s now about what AI can remember, plan, and actually do for you. That was a turning point.

Its the rise of AI Agents.

This article isn’t about APIs, frameworks, or how to wire up an agent loop. It’s about how this shift changes the way we work, the way we build systems, and the role humans will play when AI can act, plan, and collaborate on its own.

What Makes an Agent Different?

So what’s the difference between “just an AI model” and an “agent”? At its heart, an agent is like an AI with initiative. It’s not just waiting for you to give precise instructions — it can decide the how once you give it a what.

Think of it this way:

A generative model creates.
A tool-using model executes instructions.
An agent thinks, decides, and acts — sometimes even without you micro-managing.

Agents can:

Remember context (not just within one chat, but over longer sessions).
Think ahead (try strategies, backtrack if something fails).
Take actions (call tools, run processes, talk to other agents).
Adapt (shift paths based on new information).

Why Agents Actually Matter

You might wonder: “Okay, cool, they can decide and act… but so what?”

The difference is that agents shift AI from being a tool you use to becoming a teammate you orchestrate. Instead of you figuring out each step, you set a goal and let the agent handle the grind.

This changes the dynamic in a big way. Satya Nadella, CEO of Microsoft said:

“AI agents will become the primary way we interact with computers in the future. They will be able to understand our needs and preferences, and proactively help us with tasks and decision making.”

That’s not hyperbole — it’s happening. You can already see prototypes where one agent researches, another summarizes, and a third drafts an email. All you do is check the final result.

Peeking into the Future

Now, let’s take a step forward. Can you imagine a world where you don’t just have one assistant, but hundreds of agents at your disposal? Some optimize your finances, others manage your team’s workflows, a few handle customer support, while others watch your infrastructure 24/7.

Try to picture this: You’re sipping your morning coffee. Instead of opening Slack or email, you glance at your “Agent Board.” Overnight, one agent gathered competitive intel, another agent flagged bottlenecks in your codebase, and a third drafted a plan for the next sprint. Your job? Skim through, approve or reject a few things, and set new goals.

That’s the shift — you’re no longer the one doing the grunt work. You’re the orchestrator. The one defining what needs to happen, while agents figure out how to make it happen.

And as Shyamal from OpenAI pointed out:

“The scarce thing becomes ‘who can orchestrate resources well’ — compute, capital, access to data, and human/expert judgment.”

That’s the key. In this world, the real advantage won’t just be writing prompts or pulling every resources or even about creating agents — anyone can do them. The differentiator will be:

How efficiently you can orchestrate them.
How you manage scarce compute and resources.
How you apply judgment to direct them toward meaningful outcomes.

Human intuition "deciding what matters and what doesn’t" becomes more valuable than ever.

Why Building Around Agents Wins

Here’s an important point: businesses that try to bolt agents onto existing systems will move slower than those that build systems around agents from day one.

Think about it. If your workflows are already designed with agents in mind, scaling becomes natural. Agents aren’t forced into awkward places — they’re core to the system.

And the companies that figure this out? They’ll outpace everyone else. Because in the future, being “agent-first” will be like being “mobile-first” was a decade ago: the difference between thriving and barely surviving.

Closing Thoughts

Agents aren’t sci-fi. They’re not coming — they are already here. The shift from “tools that respond” to “agents that act” is happening right now.

It won’t be perfect tomorrow. We’ll hit weird edge cases. There’ll be trust issues, surprises, bugs. But the momentum is real.

So whether you’re a developer, a founder, or just someone curious about where AI is going, it’s worth asking yourself:

"Am I building tools for today, Or am I designing systems ready for the world of agents?"

Everyone Is Talking About AI Agents — Here’s What They’re Missing

Jefree Sujit — Sun, 14 Dec 2025 09:27:23 +0000

AI agents are everywhere today.

From image generation to content creation, from coding assistants to autonomous research tools, the word agent has quietly become the default label for anything that feels a little more capable than a chatbot.

But if you look closely at most explanations, something feels incomplete. We jump straight into frameworks, abstractions, and applications, without a clear mental model of what an agent actually is.

So let’s slow down and ask the real question:

What actually makes an agent an agent?

This is the first of a three-part series on AI Agents. In this article, we’ll establish the foundational concepts. Later in the series, we will dive into architectural patterns, control flows, and state management.

Let’s Start With the Simplest Possible Interaction

Consider the most basic thing we can do with a model: give it a prompt.

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.chat.completions.create({
  model: "gpt-5.1",
  messages: [
    { role: "user", content: "Summarize the concept of AI agents" }
  ]
});

console.log(response.choices[0].message.content);

The model responds. The reasoning might be solid. The output might even be impressive.

And then… everything stops.

Nothing is remembered.
Nothing continues.
No next decision is made.

No matter how sophisticated the model is, or how carefully the prompt is engineered, this interaction lives entirely inside a single request-response boundary. The model can reason, explain, and even plan, but once the response is generated, the computation is over.

Prompt engineering can improve what the model says, but it cannot change how the system behaves.

So the natural next question becomes:

What if we make the model do more than just respond? Would that make it an Agent?

Lets dive deeper.

What If We Let the Model Act?

The obvious next step is to give the model the ability to perform actions.

We expose tools, functions that can read files, write output, search the web, or call APIs, and allow the model to invoke them.

const tools = [
  {
    type: "function",
    function: {
      name: "readFile",
      description: "Read a file from disk",
      parameters: {
        type: "object",
        properties: {
          path: { type: "string" }
        },
        required: ["path"]
      }
    }
  }
];

const response = await client.chat.completions.create({
  model: "gpt-5.1",
  messages: [
    { role: "user", content: "Read README.md and summarize it" }
  ],
  tools
});

Now the model can decide to call readFile, your application executes it, and the result is passed back to the model.

This is a major upgrade. The system can interact with the real world, not just describe it.

But even here, something subtle is missing.

The model makes a decision, triggers an action, produces a response, and then exits. It doesn’t reflect on whether the action was sufficient. It doesn’t decide whether more steps are needed. It doesn’t recover or adapt.

It can act, but it doesn’t own the process.

This is where many systems stop, and where many “agents” quietly fail to become agents.

So if prompts aren’t enough, and actions alone aren’t enough either, what actually is?

So… What Actually Makes Something an Agent?

A better way to think about agents is this:

An agent is a system that repeatedly observes its state, decides on an action, executes that action, and incorporates the result before deciding again.

This is how Andrej Karpathy, co-founder of OpenAI and EurekaLabs, describes an AI Agent:

“An agent is essentially a language model running in a loop, with access to tools and memory.”

The critical word here is loop.

As long as you know how to write a loop in your code, you already understand the core idea behind agents.

Without a loop, there is no agent.

The Loop Is the Behavior

An agent is not defined by prompts, tools, or frameworks. It is defined by what happens after the first action.

An agent repeatedly:

reasons about its current state,
decides what to do next,
executes an action,
observes the result,
and feeds that result back into the next decision.

This idea commonly appears as the ReAct pattern, short for Reason + Act, where reasoning, action, and observation are interleaved in a continuous cycle. The names don’t matter much. The repetition does.

Once this loop exists, the model stops being a passive responder and starts behaving like a system that can steer its own execution.

Let’s Build a Simple Agent (to learn how it works)

Let’s put this into practice with a real, simple agent written in JavaScript.

The goal is simple:

Explore a directory and produce a summary of all markdown files.

Dependencies

npm install openai

Tools (Real Functions)

import fs from "fs/promises";

async function listFiles(dir) {
  return await fs.readdir(dir);
}

async function readFile(filePath) {
  return await fs.readFile(filePath, "utf-8");
}

Tool Definitions

const tools = [
  {
    type: "function",
    function: {
      name: "listFiles",
      description: "List files in a directory",
      parameters: {
        type: "object",
        properties: {
          dir: { type: "string" }
        },
        required: ["dir"]
      }
    }
  },
  {
    type: "function",
    function: {
      name: "readFile",
      description: "Read a text file",
      parameters: {
        type: "object",
        properties: {
          filePath: { type: "string" }
        },
        required: ["filePath"]
      }
    }
  }
];

The Agent Loop

import OpenAI from "openai";

const client = new OpenAI();

async function runAgent(goal) {
  const messages = [
    {
      role: "system",
      content:
        "You are an agent. Decide what action to take next and continue until the task is complete."
    },
    { role: "user", content: goal }
  ];

  let done = false;

  while (!done) {
    const response = await client.chat.completions.create({
      model: "gpt-4.1",
      messages,
      tools
    });

    const message = response.choices[0].message;
    messages.push(message);

    if (message.tool_calls) {
      for (const call of message.tool_calls) {
        const args = JSON.parse(call.function.arguments);

        let result;
        if (call.function.name === "listFiles") {
          result = await listFiles(args.dir);
        } else if (call.function.name === "readFile") {
          result = await readFile(args.filePath);
        }

        messages.push({
          role: "tool",
          tool_call_id: call.id,
          content: JSON.stringify(result)
        });
      }
    } else {
      done = true;
      console.log(message.content);
    }
  }
}

runAgent("Summarize all markdown files inside the ./docs directory");

This is an agent not because of the tools or the model, but because the system keeps deciding.

The loop is what turns capability into behavior.

Agents vs Workflows

It’s also important to distinguish agents from workflows.

A workflow executes a predefined sequence of steps, for example LangChain or a sequence of predefined individual tasks. It assumes you already know what needs to happen and in what order. This makes workflows predictable, cheaper, and easier to debug.

Agents, on the other hand, are useful when:

The path to the goal is unknown
Intermediate results affect decisions
The environment is dynamic
Creativity or exploration is required

When Not to Use an Agent

Agents are not cheap.

They perform multiple calls, consume more tokens, cost more money, introduce latency, and are harder to reason about. Debugging agent behavior can be challenging because decisions emerge dynamically rather than following a script.

If your problem already has a clear structure, a known sequence of steps, a deterministic transformation, or a fixed flow, introducing an agent only adds complexity. In those cases, simple tool calling or a workflow is often the cleaner and more reliable solution.

Agents should be used when autonomy and adaptation matter more than predictability.

Closing Thoughts

Once you stop thinking of agents as a special kind of model and start thinking of them as loops driven by decisions, everything becomes clearer.

Prompts don’t create agents.
Tools don’t create agents.
Frameworks don’t create agents.

Loops do.

Once you internalize that agents are just decision-making loops running over time, building them stops feeling mysterious or complex. That shift in thinking is where real agentic systems begin.

This article is all about the basic understanding of what an AI Agent is and how it works. In the next part of the series, we’ll dive deeper into how control flow is actually implemented with modern agent frameworks and how explicit state machines compare to free-running agent loops.

How to build your own file-system MCP server (A step-by-step guide)

Jefree Sujit — Tue, 14 Oct 2025 18:56:20 +0000

MCP servers are powerful: they let clients (IDEs, agents) interact with remote or local features and services in a structured, RPC-style way. But what if you want to build your own MCP server — one tailored to your domain or use case?

Welcome to the last part of the three-part series on MCP (Model Context Protocol). If you haven’t checked the previous parts, feel free to check Part 1 (what MCP is, and its underlying concept) and Part 2 (Connecting existing MCP servers and popular MCPs)

In this final part, we’ll walk through how to build a file-system MCP server — i.e. an MCP server that lets an IDE or any MCP client interact with your file system over MCP. You can use it locally or even host it remotely, depending on your needs.

What you’ll walk away with

By the end of this article, you will be able to:

Understand the difference between local vs remote MCP servers
Build a simple file-system MCP server (list, read, write, delete files)
Connect your custom MCP server with clients like Cursor, Windsurf, etc.
Package and publish your MCP server as an npm package

Why build your own MCP server?

Before jumping into code, let’s consider why you might want a custom MCP server:

Standard MCP servers give you generic data or tools, but you may want domain-specific ones (e.g. file system, database, cloud storage, diagnostics).
With your own MCP server, you control which operations are allowed, access rules, optimization / caching, and extensions.
It lets your clients (IDE extensions, agent systems) talk to your data or environment via MCP in a consistent, structured way.
You can run it locally (on the user's machine) or remotely (in a server or VM), depending on your architecture.

Types of MCP servers: Local vs Remote

Local MCP server: runs on the user’s machine (e.g. shipped with your app/CLI), communicates over stdio or IPC.
Remote MCP server: lives on a server or cluster, communicates over HTTP, WebSocket, or another network transport.

From the MCP logic’s point of view, tools / resource handlers are the same. Only the transport (stdio vs HTTP) changes.

Because file systems are inherently local, we will target a local MCP server (running on the same machine). But you can later extend it to remote transports, bridge via HTTP/WS, or host it in a container.

Setting up the codebase

Enough with the boring lectures, let's start with the actual implementation. Here’s roughly how you’d structure your project:

src/
  server.ts
  tools.ts
tsconfig.json
package.json

Tools: The Core File System Operations

Create a new file called tools.ts In tools.ts, you’ll define functions (handlers) for each operation. Each handler receives input arguments (e.g. directory path, file path, file content) and returns a result or error in MCP protocol format (or using Zod-validated schemas).

Here are the basic tool definitions you'd need:

listDirectory(dirPath: string): DirectoryListingResponse
readFile(filePath: string): FileContentResponse
writeFile(filePath: string, content: string): FileWriteResponse
removeFile(filePath: string): FileDeleteResponse

Here's a simple implementation of tools.ts to setup necessary tools for the filesystem:

// tools.ts
export async function listDirectory(args: { path: string }) {
  const abs = resolveSafe(args.path);
  const stat = await fs.stat(abs);
  if (!stat.isDirectory()) {
    throw new Error(`${args.path} is not a directory`);
  }
  const names = await fs.readdir(abs);
  const entries = await Promise.all(
    names.map(async (name) => {
      const child = path.join(abs, name);
      const st = await fs.stat(child);
      return { name, isDirectory: st.isDirectory() };
    })
  );
  return { entries };
}

export async function readFile(args: { path: string }) {
  const abs = resolveSafe(args.path);
  const content = await fs.readFile(abs, "utf-8");
  return { content };
}

export async function writeFile(args: { path: string; content: string }) {
  const abs = resolveSafe(args.path);
  await fs.writeFile(abs, args.content, "utf-8");
  return { success: true };
}

export async function removeFile(args: { path: string }) {
  const abs = resolveSafe(args.path);
  await fs.unlink(abs);
  return { success: true };
}

You should wrap in try / catch and handle errors (e.g. file not found, permission denied) gracefully, returning structured error objects.

Using Zod (or similar) you can define input & output schemas to validate and serialize them.

Setting up the MCP Server files

Now that we have the tools setup ready, lets start with the actual MCP server file setup.

In server.ts, we'll:

Import MCP server from @modelcontextprotocol/sdk
Import the transport (e.g. StdioServerTransport as we are build a local MCP server)
Instantiate the server
Register the required tools (from tools.ts)
Start / connect the transport

// server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";  
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";  
import * as fsTools from "./tools";

async function main() {
  const server = new McpServer({
    name: "fs-mcp-server",
    version: "0.1.0",
  });

  server.registerTool("listDirectory", fsTools.listDirectory);
  server.registerTool("readFile",     fsTools.readFile);
  server.registerTool("writeFile",    fsTools.writeFile);
  server.registerTool("removeFile",   fsTools.removeFile);

  const transport = new StdioServerTransport();
  await server.connect(transport);

  console.log("fs-mcp-server is running");
}

main().catch((err) => {
  console.error("Server failed:", err);
  process.exit(1);
});

At runtime, this listens for incoming MCP RPCs over stdio and invokes your file system handlers.

Build & run it, test with a client

Lets setup the package.json with npm init and install necessary dependencies. It should look something like this:


{
  "name": "fs-mcp-server",
  "version": "0.1.0",
  "main": "dist/server.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^…",
    "zod": "^…",
    // other required dependencies
  }
}

Set up tsconfig.json so tsc compiles into dist/.

Then run:

npm run build
npm run start

That should launch your MCP server.

Client Connection Setup

The next setup is to connect and test the local MCP. Once you have the local MCP server running, go to your MCP Client (like Cursor, VS Code, or Claude Desktop) settings and add the MCP Config.

Here’s a valid MCP config you can drop into an IDE or MCP-client config to connect a local MCP server via stdio / command. You can adjust command, args, working_directory, etc., to match your setup.

{
  "mcpServers": {
    "my-fs-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/your/mcp-project/dist/server.js"],
      "env": {
        "FS_ROOT": "/absolute/path/to/exposed/root"
      }
    }
  }
}

Once you have configured the MCP properly, the MCP client would automatically verify and list all available tools from our MCP. This shows the MCP is properly connected.

Now you can go to the Chat and ask the Agent to use our MCP to perform any file related operations and you'll see the Agents making necessary calls to our MCP tools to perform the actions.

Publishing & Distribution

Once it works locally and you're confident, the next step is to make it available globally:

Publish as an npm package, so users can npx fs-mcp-server. Here's the official guide on how to publish this package into NPM

Once you've published you can connect your MCP directly with your npx command:

{
  "mcpServers": {
    "my-fs-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["fs-mcp-server"]
    }
  }
}

Verify the MCP by connecting with your MCP Client.

Some extensions and cool things you can add next

Once the basics are working, here are ideas to expand:

Add rename / move and create directory / delete directory
Support search / glob matching inside a directory
Handle binary files (base64 encoding or streaming buffers)
Support remote transport (HTTP, WebSocket) so you can host it
Offer mounting multiple roots under alias names (e.g. workspace/, config/)
Add validation schemas (using Zod) to enforce input/output correctness

Conclusion & next steps

In this final part of the series, you’ve learned how to build your own MCP server — specifically a file-system server — from the ground up.

To quickly try our the filesystem MCP directly in your IDE, check out this NPM package. To see the full implementation and reference code along with the mini version of Gemini CLI (with filesystem capabilities), check out this GitHub repo.

If you found this helpful, I’d greatly appreciate your support — a like, share, or comment helps a ton. And if you run into any bottlenecks, questions, or ideas while building your MCP server, feel free to drop a comment — I’m happy to help.

Getting Started with MCP: 10 Essential MCPs you must try

Jefree Sujit — Fri, 26 Sep 2025 20:11:01 +0000

If you’re a developer using Cursor, Windsurf, or Claude, or you frequently build things that mix code, docs, tasks, and design — you’re probably itching to connect more of your tools directly into your workflow. That’s where MCP (Model Context Protocol) comes in: it lets your tools (MCP servers) talk to your agent client in a standardized way, giving the agent access to context it wouldn’t otherwise have.

This article is second of a three-part series where we go deeper into MCP. In the first part of this series, we explored what the Model Context Protocol (MCP) is, its underlying concepts and the "why" behind it. If you haven’t checked it yet, you can read it here

In this article, we’ll cover:

How to add an MCP to client (like Cursor, Windsurf, or Claude Desktop).
How to configure mcp.json.
Commonly used popular MCP servers (Notion, Linear, GitHub, Figma, Supabase).
Sample system prompts you can try with each MCP.

By the end, you’ll be able to connect to MCPs from your IDE and start making them part of your everyday workflow.

How to Add an MCP Client & Configuration

Now, let’s get practical. To connect MCP servers (tools like Notion, Linear, Supabase, etc.) to your client, it basically requires two things:

Enabling MCP client support in your tool (Cursor/Windsurf/Claude).
Writing a config (usually mcp.json or similar), pointing to MCP servers with correct auth.

Here’s how to set up your environment with sample configuration and where to put the file.

1. Create a new config file

Make a file named mcp.json in your project (or in a global config location).

Here’s a generic template:

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp",
      "auth": {
        "type": "oauth",
        "token": "YOUR_NOTION_OAUTH_TOKEN_HERE"
      }
    },
    "linear": {
      "url": "https://mcp.linear.com",
      "auth": {
        "type": "apiKey",
        "key": "YOUR_LINEAR_API_KEY_HERE"
      }
    }
  }
}

You’ll replace the placeholder strings with your real tokens or keys, and ensure the URLs are correct.

2. Client-specific Setup

Here are the instructions for some of the common clients on where to put the config file and how to enable MCP support.

Cursor

Place the file in your project root as .cursor/mcp.json.
If you want it globally, you can also put it in ~/.cursor/mcp.json so it applies to all projects.
In Cursor → Settings → Context / MCP, toggle “Enable MCP servers” if it’s not already.
Sometimes you may need to restart Cursor or refresh in Settings for the new MCP servers to show up.

Windsurf

Add mcp.json in the root of your workspace/project directory.
In Windsurf → Plugins or Integrations → *“Add external MCP server” * (or equivalent settings panel) — paste the URL or enter the command/config.
If the server is remote, provide auth credentials in the config. If local, ensure the command/args are provided if required.

Claude Desktop

On macOS: edit ~/Library/Application Support/Claude/claude_desktop_config.json (or the equivalent config file path).
On Windows/Linux: similar config paths (check Claude’s docs).
Insert your mcpServers entries into that config file.
Make sure MCP is enabled in Claude’s settings. Sometimes permissions (for local servers or filesystem access) must be granted.

Popular MCP Servers You Can Try Now

Here are some of the most useful MCPs you can start with.

1. Notion

Notion isn’t just a note-taking tool — it’s where a lot of devs keep documentation, plans, and even databases. Notion MCP gives your agent secure access to your Notion workspace: docs, databases, comments, etc. Great for pulling in specs, PRDs, knowledge base content without manual export.

Config:

{
  "mcpServers": {
    "notionMCP": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"]
    }
  }
}

Try this prompt:

“Fetch the product requirements spec from Notion for Project Alpha and give me a bullet-list summary of action items.”

👉 Reference: Notion MCP GitHub

2. GitHub

GitHub is where your code lives. The GitHub MCP enables your agent to access repos, pull requests, issues. Helpful for code review, fetching code context, auto-generating changelogs etc.

Config:

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_PAT"
      }
    }
  }
}

Try this prompt:

“List open PRs in repo/backend, identify failing ones, and draft a summary of required changes.”

👉 Reference: GitHub MCP

3. Linear

Linear is popular for issue and project tracking. With Linear MCP, your agent can fetch ticket info, read acceptance criteria, update statuses, etc. Good for managing dev workflows.

Config:

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"]
    }
  }
}

Try this prompt:

“Get the Linear ticket with ID LNR-123, read its content and acceptance criteria, then generate a implementation plan.”

👉 Reference: Linear MCP

4. Figma

Design files often hold important context. For designers or front-end folks, the Figma MCP lets you query design docs or pull specs directly.

Config:

{
   "mcpServers": {
     "figmaRemoteMcp": {
       "url": "https://mcp.figma.com/mcp"
     }
   }
 }

Try this prompt:

"Fetch the latest login screen design from Figma and generate a React component scaffold with styles.”

👉 Reference: Figma MCP

5. Supabase

Supabase is a backend-as-a-service. With the Supabase MCP, you can query your DB directly through your client. It gives your agent access to database schema, table data, and allows queries. Useful for backend dev, data workflows, etc.

Config:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase",
        "--read-only",
        "--project-ref=<project-ref>"
      ],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "<access-token>"
      }
    }
  }
}

Try this prompt:

“Fetch the users table schema from Supabase, generate TypeScript types, and suggest indexes for queries on created_at.”

👉 Reference: Supabase MCP

6. Slack

Slack has become a goto communication channel for most startups and developer community. Slack MCP could pull messages, notifications, status checks, send messages, etc. Slack MCP also helps link communication data into your agent workflows.

Config:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": [
        "-y",
        "slack-mcp-server@latest",
        "--transport",
        "stdio"
      ],
      "env": {
        "SLACK_MCP_XOXP_TOKEN": "xoxp-..."
      }
    }
  }
}

Try this prompt:

“Pull messages from #dev channel in Slack for the past week, and summarize top blockers mentioned by team; then suggest issues I should prioritize.”

👉 Reference: Slack MCP

7. File System

Sometimes you just need your agent to access your local files. The File System MCP lets your agent access your local files — code, configs, markdown documentation, etc. Great when you want the agent to search your project or read local docs.

Config:

{
  "mcpServers": {
    "filezop": {
      "type": "stdio",
      "command": "npx",
      "args": ["filezop", "start"]
    }
  }
}

Try this prompt:

“Search for files in directory that has instances of TODO and give me a quick task list on what all have to be done.”

👉 Reference: File System MCP

8. Playwright

Playwright is great for browser automation and testing. The Playwright MCP can spin up browser sessions and test flows and your agents can navigate web pages, fetch data, fill forms, test UIs automatically

Config:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}

Try this prompt:

“Use Playwright MCP to check whether my website’s signup form is broken: navigate to signup page, simulate signup, report any JS errors.”

👉 Reference: Playwright MCP

9. Postman

For developers working with APIs, Postman MCP enables your agent to access API collections in Postman, see endpoints, test APIs, environments. Useful for testing, automating API tasks.

Config:

{
  "mcpServers": {
    "postman_mcp_server": {
      "url": "https://mcp.postman.com/minimal",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Try this prompt:

“From my Postman collection ‘User Management’, list all endpoints tagged ‘admin’ and show their required parameters.”

👉 Reference: Postman MCP

10. Peekaboo

Peekaboo is useful for visual debugging or workflows that need UI context. It's macOS-only MCP server captures screenshots or application usage, letting AI agents see your UI or screen content. Peekaboo MCP is handy for security and observability — scanning or monitoring systems via your client.

Config:

{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": ["-y", "@steipete/peekaboo-mcp@beta"],
      "env": {
        "PEEKABOO_AI_PROVIDERS": "openai/gpt-4.1,ollama/llava:latest",
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

Try this prompt:

"Run a quick security scan on the UI application. Take a screenshot of my dashboard, highlight all buttons with duplicate labels, and list them.”

👉 Reference: Peekaboo MCP

Why MCPs Matter in Development

MCPs do more than reduce context switching. They let your editor, your agent, your workflow become aware of your tools and resources. Instead of pulling in docs manually, copying text, switching tabs, you ask your agent and it goes to the source—Notion, Linear, Supabase, GitHub, etc.

MCPs let your agents work smarter, faster, and more integrated:

Faster ramp-up on new projects because the agent already has your workspace context.
Less friction — less jumping between tools.
More consistency: your agent can operate with up-to-date info, avoiding stale docs or manual copy errors.
Scalability: as you add more tools, your agent can pull them in without extra glue code.

That's it! You’ve learned how to connect MCP clients like Claude, Cursor, and Windsurf to different MCP servers, set up the right configs, and experiment with popular MCPs like Notion, GitHub, Linear, Supabase, Postman, and more.

In the next part (Building your own MCPs), we’ll go beyond using existing MCPs and dive into how to build your own MCP server, so you can integrate your custom tools and workflows.

What is Model Context Protocol (MCP) and Why Everyone is Talking About It

Jefree Sujit — Sun, 21 Sep 2025 05:25:33 +0000

If you’ve been following the AI space recently, you’ve probably heard the term Model Context Protocol (MCP) being tossed around. It’s one of those buzzwords that keeps showing up in developer discussions, conference talks, and product announcements.

But what exactly is MCP? Why was it introduced? And why are people so excited about it? More importantly why does it matter to developers, tool providers, and AI enthusiasts alike?

Welcome to the first article in my three-part series on MCP. In this series, I will cover the fundamentals of MCP and how to get started, popular MCPs and how to use it in daily work, and finally on how to build your own MCP server.

The Problem Before MCP

Let’s start with the old way.

Imagine you’re building an AI agent that needs to interact with Slack. You’d want it to post updates, respond to messages, or trigger workflows. Without MCP, you’d have to:

Write a wrapper around Slack’s API
Handle all the request/response logic yourself
Repeat the same for every other tool you wanted to integrate (GitHub, Notion, Jira, Google Drive, etc.).

Every developer was reinventing the wheel. Worse, every consumer of these integrations needed their own custom logic to “teach” their model how to use these APIs. It was slow, inconsistent, and painful to scale.

Enter MCP (Our Hero)

To address this, Anthropic (the team behind Claude) introduced the Model Context Protocol. MCP is an open standard that defines how AI models, clients, and external tools can interact cleanly.

The idea is simple but powerful:

Instead of writing custom wrappers, a provider can expose an MCP server.
An MCP client (like an IDE, an AI assistant, or another tool) connects to the server and fetches what’s available.
The model then uses this connection to call functions directly, without needing bespoke glue code

Okay, How MCP Works?

Think of MCP as a three-part ecosystem:

MCP Server: Exposes a set of functions or tools. This could be Slack, GitHub, Notion, or even a custom app you’ve built.

MCP Client: Acts as the bridge between the model and the server. Clients could be Cursor, GitHub Copilot, or Claude desktop apps — essentially anything that embeds a model and wants to extend its capabilities.

The Model: Once connected, the model can “see” what functions are available and use them on demand.

This design means once a model is connected to an MCP server, it can instantly fetch all available functions — no manual integration required.

MCP Is a Spec, Not the API Itself

To put it simply, MCP is to agents what OpenAPI spec is to APIs.

Think about OpenAPI for a second: it doesn’t give you the API itself. Instead, it’s a contract — a structured way of saying, “Here are the endpoints, here’s what they accept, here’s what they return.” It’s not the server, not the playground, not the implementation — just the map that tells you what’s out there.

MCP plays the same role, but in the agent world. An MCP server doesn’t expose the tool directly for you to call like a REST API. Instead, it exposes a spec: “Here are the tools I provide, here’s how they work.” It’s then up to the model (or the agent framework you’re using) to read that spec, decide which tool fits the problem, and call it correctly.

So, instead of thinking of MCP as an “API you hit,” it’s better to think of it as the blueprint that makes agent-tool interaction consistent, interoperable, and portable.

And Why the Buzz?

MCP is attracting attention because it addresses a foundational problem for AI: tool interoperability at scale.

Here’s why it matters:

No more duplicate wrappers → Providers can expose their tools once, and any client can consume them.
Discoverability built in → Models can dynamically fetch and understand what tools are available.
Standardization → A common protocol lowers the barrier to integrating tools.
Scalability → Imagine hundreds of MCP servers; an AI client could connect to all of them without bloated, custom integrations.
Openness → It’s not limited to big providers. Anyone can create an MCP server, from a personal project to enterprise-grade software.

If this sounds exciting, you’re not alone — MCP adoption is growing quickly. It could become a foundational piece of how AI systems interact with the world. Just like HTTP unlocked the modern web, MCP could unlock the next generation of AI-powered applications.

And the best part? It’s open, extensible, and still evolving — which means we’re just at the beginning.

This post was all about the fundamentals and the "why" behind MCP. In my next one, I’ll walk through how to get started with MCP and some popular MCP servers you can already try out — from developer tools to productivity apps — and how to connect them in your own IDEs.