AI Agents & Model Context Protocol (MCP)

Relevant source files

The following files were used as context for generating this wiki page:

• packages/farm-mcp/src/index.ts
• packages/farm-mcp/src/index.test.ts
• packages/farm-mcp/src/standalone.test.ts
• packages/farm/src/llms-txt.ts
• packages/farm/src/tests/mcp-production.test.ts
• AGENTS.md

AI Agents in Farm.js utilize the Model Context Protocol (MCP) to interact with application logic and external data. This system enables applications to expose tools, resources, and instructions to language models in a standardized format. The framework provides agent-native infrastructure by default, supporting both dedicated MCP servers and integrated API-based tools.

Sources: AGENTS.md:1-10, packages/farm/src/llms-txt.ts:1-10

Architecture and Protocol Implementation

Farm.js implements MCP through a plugin-based architecture that mounts an MCP-compliant endpoint (typically at /api/mcp) to handle JSON-RPC requests. The protocol supports standard operations like listing tools and calling specific functions.

MCP Request Flow

The following diagram illustrates how an agent request is processed through the Farm.js MCP handler.

The system ensures that server-side logic remains isolated from the client while providing a bridge for agents to perform permitted actions.

Sources: packages/farm-mcp/src/index.test.ts:70-85, packages/farm/src/tests/mcp-production.test.ts:10-25

Tool Definition and Registration

Tools are the primary mechanism for agents to perform actions. Farm.js supports two types of tools:

1. Endpoint Tools: Mounted routes (like GET or POST endpoints) that are exposed as tools.
2. Standalone Tools: Function-based tools defined directly in the configuration using defineTool.

Standalone Tool Configuration

Standalone tools use Zod schemas for input and output validation. The execute function receives the validated input along with a context object containing authorization details and the original request.

import { defineTool } from "@farm.js/mcp";
import { z } from "zod";

export const searchTool = defineTool({
  name: "search_projects",
  description: "Search for projects by query",
  inputSchema: z.object({
    query: z.string().min(1)
  }),
  execute: async ({ query }, { authorization }) => {
    // Implementation logic
    return { results: [], actor: authorization.subject };
  }
});

Sources: packages/farm-mcp/src/standalone.test.ts:45-65, packages/farm/src/tests/mcp-production.test.ts:100-115

Security and Authorization

Security is enforced through an authorize hook in the MCP configuration. This hook controls tool visibility (discovery) and execution permissions based on the request headers (e.g., Bearer tokens).

Authorization Policy Logic

• Discovery: The tools/list method only returns tools the current principal is authorized to see.
• Execution: The tools/call method validates that the principal has permission to run the specific tool before execution begins.
• Isolation: Each tool execution receives a unique context, ensuring principals cannot leak permissions across concurrent calls.

Context Field	Type	Description
server	Object	Contains server name, version, and path.
tools	Array	A frozen list of configured tool references.
request	Request	The original HTTP request object.
authorization	Object	The resolved principal identity (subject, tenant, etc.).

Sources: packages/farm-mcp/src/index.test.ts:250-275, packages/farm-mcp/src/standalone.test.ts:200-215, packages/farm/src/tests/mcp-production.test.ts:120-135

Agent Discovery and Context (llms.txt)

To help agents understand the application structure, Farm.js serves an llms.txt file at the root. This file is a Markdown index that defines what the site is and where its readable pages live.

llms.txt Components

• Index (/llms.txt): A structured list of static pages and their summaries.
• Full Version (/llms-full.txt): The index with each page's Markdown content inlined for dense context delivery.
• Markdown Mirrors: Pages are linked to their .md versions to provide LLMs with clean text without UI overhead.

Configuration Summary

The mcp property in farm.config.ts controls the agent interface behavior.

Option	Type	Default	Description
name	string	N/A	The name of the MCP server.
tools	Array	[]	List of defineTool results or endpoint references.
authorize	Function	Required*	Validates requests and returns authorized tool names.
allowUnauthenticated	boolean	false	If true, permits access without the authorize hook.

*Note: Farm.js requires an explicit authorization posture; it will throw an error if neither authorize nor allowUnauthenticated is provided.

Sources: packages/farm-mcp/src/index.test.ts:90-105, packages/farm/src/tests/mcp-production.test.ts:115-130

Conclusion

The AI Agents and MCP infrastructure in Farm.js provides a secure, typed, and standardized way to expose application capabilities to language models. By combining structured tool definitions with automated discovery files like llms.txt, the framework ensures that applications are "agent-native" while maintaining strict security boundaries and predictable full-stack behavior.