AgileBuilder logoAgileBuilder
Back to docs

MCP Server

Learn about AgileBuilder's built-in MCP stdio server and the tools and document resources it exposes to AI tools

What is MCP

MCP (Model Context Protocol) is an open protocol that lets AI tools — such as Cursor, Claude Code, and Claude Desktop — call external tools and read external data in a standardized way.

AgileBuilder ships with a built-in MCP server. Once connected, your AI can:

  • Query the template and document resources in your workspace
  • Read your team's guideline documents as context for code generation
  • Scaffold projects directly from templates

AgileBuilder itself does not call any LLM. It only provides templates and documentation to the AI tool you use, which performs the actual code generation.

The AgileBuilder MCP Server

The AgileBuilder MCP server is a standalone stdio process, installed together with the agilebuilder npm package as a dedicated executable: agilebuilder-mcp.

npm install -g agilebuilder

It is not an HTTP server: there is no listening port, no daemon, and nothing to start manually. MCP-capable clients (Cursor, Claude Code, etc.) launch the process over stdio when needed and it exits automatically when the session ends.

The MCP server shares the same local data directory (~/.agilebuilder/v2) as the CLI and operates on the current workspace — the one shown by ag space current. Switching workspaces with the CLI affects the MCP server too:

ag space use local        # use the local workspace
ag space use <space-id>   # use a cloud workspace

MCP Tools

The server exposes 4 tools that the AI calls to query resources and generate projects.

list_resources

Lists resources in the current workspace.

Parameters:

ParameterTypeRequiredDescription
typetemplate | docNoFilter by resource type

Returns: an object containing workspaceId, the resource list items, and the total count.

search_resources

Searches resources in the current workspace by keyword.

Parameters:

ParameterTypeRequiredDescription
keywordstringNoSearch keyword
typetemplate | docNoFilter by resource type

Returns: same structure as list_resources.

get_resource

Reads a single resource from the current workspace.

Parameters:

ParameterTypeRequiredDescription
resourceIdstringYesResource ID

Returns: full resource details (name, type, Git URL, description, tags; document resources also include the content body).

create_project

Scaffolds a project from a template resource or a direct Git URL.

Parameters:

ParameterTypeRequiredDescription
targetPathstringYesLocal directory where the project is generated
resourceIdstringOne of twoTemplate resource ID in the current workspace
gitUrlstringOne of twoDirect Git template repository URL
branchstringNoGit branch
subdirstringNoTemplate subdirectory within the repository
variablesobjectNoTemplate variables as a JSON object
overwritebooleanNoAllow writing into a non-empty directory
keepGitbooleanNoKeep the template repository's .git directory
allowHooksbooleanNoAllow template hooks to run

At least one of resourceId and gitUrl must be provided. When a project is created from a cloud template resource, the MCP server also records a resource access.

Example arguments:

{
  "resourceId": "1",
  "targetPath": "./my-app",
  "variables": { "appName": "my-app" },
  "allowHooks": false
}

MCP Resources

In addition to tools, the server exposes document content as MCP resources that the AI can read on demand:

URIDescription
agilebuilder://docs/usageAgileBuilder usage guide
agilebuilder://usage/agent-policyAgent policy — rules the AI should follow when calling tools
agilebuilder://docs/catalogCatalog of document resources in the current workspace
agilebuilder://local/docs/<id>Content of a local document resource
agilebuilder://cloud/docs/<id>Content of a cloud document resource

agilebuilder://docs/catalog changes dynamically with the documents in the current workspace. The AI typically reads the catalog first, then fetches a specific document via agilebuilder://local/docs/<id> or agilebuilder://cloud/docs/<id>. Reading cloud documents requires a cloud workspace to be selected.

Client Configuration

MCP-capable clients usually connect to a stdio MCP server through a JSON snippet. The generic configuration for AgileBuilder is:

{
  "mcpServers": {
    "agilebuilder": {
      "command": "agilebuilder-mcp"
    }
  }
}

This tells the client to start an MCP server named agilebuilder by running the agilebuilder-mcp command. It requires a global install (npm install -g agilebuilder) so the command is available on PATH.

For client-specific configuration locations and syntax, see:

Relationship with Cloud Workspaces

When you are not logged in, the MCP server works against the local workspace, and the AI can only access resources stored on your machine.

After signing in with ag login and switching to a cloud workspace via ag space use <space-id>, the MCP server can access that workspace's templates and documents — so the AI reads the latest guidelines your team maintains in the cloud. Your role permissions in the cloud workspace (owner / admin / member) also constrain what MCP operations can do.

Next Steps