# How Agent-Native Integrates with MCP (Model Context Protocol): Complete Implementation Guide

> Learn how Agent-Native integrates with MCP via its built-in connector. Discover auto-exposed actions, HTTP endpoints, and embedded React components for seamless implementation.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: how-to-guide
- Published: 2026-06-28

---

**Agent-Native integrates with MCP through a built-in connector that mounts an HTTP endpoint at `/_agent-native/mcp`, automatically exposes actions as protocol tools, and renders embedded React components via the `mcpApp` metadata field.**

Agent-Native is an open-source framework for building AI-native applications. According to the BuilderIO/agent-native source code, the framework provides first-class support for the Model Context Protocol by implementing a server-side plugin system that transforms every application into an MCP host.

## The MCP Server Plugin: Mounting the Endpoint

The integration starts with a dedicated server plugin that instantiates the MCP host. In [`templates/plan/server/plugins/00-mcp.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/plan/server/plugins/00-mcp.ts), the framework imports `mountMCP` from `@agent-native/core/mcp` and registers the protocol endpoint.

This plugin creates the HTTP route `/_agent-native/mcp` (e.g., `https://plan.agent-native.com/_agent-native/mcp`), which becomes the single entry point for all MCP clients.

```typescript
// templates/plan/server/plugins/00-mcp.ts
import { mountMCP } from "@agent-native/core/mcp";

export const mcpPlugin = async () => {
  // Mount the MCP server at /_agent-native/mcp
  await mountMCP({ basePath: "/_agent-native/mcp" });
};

```

## Exposing Actions as MCP Tools

Once the endpoint is active, Agent-Native automatically surfaces actions defined under `templates/plan/actions/*` as callable MCP tools. Each action uses the `defineAction` helper from `@agent-native/core/actions`.

### Automatic Action Discovery

The framework scans the actions directory and registers each export as an available tool. When an external MCP client (such as Claude, ChatGPT, or a custom host) invokes the action, the framework routes the request to the corresponding handler.

### Embedding UI with mcpApp

Actions can expose a dedicated UI for MCP contexts by adding the `mcpApp` field to their definition. This field contains an `embedApp` function that returns a React component, allowing the MCP host to render the interface inline.

```typescript
// templates/plan/actions/create-visual-plan.ts
import { defineAction } from "@agent-native/core/actions";

export const createVisualPlan = defineAction({
  name: "create-visual-plan",
  // action implementation …
  handler: async (input) => { /* … */ },

  // MCP metadata – renders a React view when called from an MCP host
  mcpApp: {
    embedApp: () => import("@/app/components/VisualPlanEditor"),
  },
});

```

When an external agent calls this action, it receives the result alongside the UI component defined in `mcpApp`, which the host can render directly.

## Skill Metadata and Discovery

The MCP URL is baked into the application’s skill descriptor at [`templates/plan/agent-native.app-skill.json`](https://github.com/BuilderIO/agent-native/blob/main/templates/plan/agent-native.app-skill.json). This JSON file includes an `"mcpUrl"` field that points to the mounted endpoint, enabling external agents to discover the MCP capabilities automatically.

```json
{
  "name": "visual-plan",
  "mcpUrl": "https://plan.agent-native.com/_agent-native/mcp"
}

```

## Detecting MCP Context in the UI

Components can detect whether they are running inside an MCP embed surface using helper functions. In [`templates/plan/app/lib/mcp-embed.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/plan/app/lib/mcp-embed.ts), the `isMcpEmbedSurface` utility checks for the presence of `window.__MCP_EMBED__`.

```typescript
// templates/plan/app/lib/mcp-embed.ts
export const isMcpEmbedSurface = (): boolean =>
  typeof window !== "undefined" && !!window.__MCP_EMBED__;

```

This allows the UI to adjust its behavior—such as hiding navigation bars or rendering simplified views—when displayed within an MCP host.

## Two-Way Integration: Calling External Agents

The integration works bidirectionally. While the app exposes its own actions as MCP tools, it can also call external MCP hosts. External agents request actions via the standard MCP endpoint, receive the JSON result, and can render the returned `mcpApp` UI inline.

```typescript
// External agent (e.g., Claude Code)
const result = await fetch(
  "https://plan.agent-native.com/_agent-native/mcp/create-visual-plan",
  { method: "POST", body: JSON.stringify({ /* input */ }) }
).then((r) => r.json());

// If the action returned a `mcpApp`, the agent can embed it:
if (result.mcpApp) {
  displayEmbeddedResult(result.mcpApp);
}

```

## Summary

- **Mounting**: The server plugin at [`templates/plan/server/plugins/00-mcp.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/plan/server/plugins/00-mcp.ts) calls `mountMCP` to create the `/_agent-native/mcp` endpoint.
- **Action Exposure**: All actions in `templates/plan/actions/*` are automatically registered as MCP tools.
- **UI Embedding**: The `mcpApp.embedApp` field in action definitions renders React components inside MCP hosts.
- **Discovery**: The `mcpUrl` field in [`templates/plan/agent-native.app-skill.json`](https://github.com/BuilderIO/agent-native/blob/main/templates/plan/agent-native.app-skill.json) enables automatic endpoint detection.
- **Context Detection**: Utilities like `isMcpEmbedSurface` in [`templates/plan/app/lib/mcp-embed.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/plan/app/lib/mcp-embed.ts) allow components to adapt to MCP environments.

## Frequently Asked Questions

### What is the Model Context Protocol (MCP)?

The Model Context Protocol is an open standard that enables AI models to securely connect to external data sources and tools. It defines a standardized way for agents to discover capabilities, invoke functions, and render UI components across different hosts.

### How do I enable MCP in my Agent-Native application?

Enable MCP by creating a server plugin that imports `mountMCP` from `@agent-native/core/mcp` and calling it with your desired base path, typically in a file like [`templates/plan/server/plugins/00-mcp.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/plan/server/plugins/00-mcp.ts). Ensure your [`agent-native.app-skill.json`](https://github.com/BuilderIO/agent-native/blob/main/agent-native.app-skill.json) includes the `mcpUrl` field pointing to this endpoint.

### Can I customize the UI shown to MCP clients?

Yes. Any action can expose a custom UI by adding the `mcpApp` field to its definition and providing an `embedApp` function that returns a React component. The component can also use `isMcpEmbedSurface` to detect when it is running inside an MCP host and adjust its layout accordingly.

### Where is the MCP endpoint configured?

The endpoint path is configured in the server plugin at [`templates/plan/server/plugins/00-mcp.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/plan/server/plugins/00-mcp.ts) via the `basePath` parameter passed to `mountMCP`. The default and example configuration uses `/_agent-native/mcp`, and this URL is published in [`templates/plan/agent-native.app-skill.json`](https://github.com/BuilderIO/agent-native/blob/main/templates/plan/agent-native.app-skill.json) for agent discovery.