☕ Looking for Java? See Java Capabilities | 📘 Looking for TypeScript? See TypeScript Capabilities

Capabilities System¶

Named services that agents provide for discovery and dependency injection

Note: This page shows Python examples. See meshctl man capabilities --typescript for TypeScript or meshctl man capabilities --java for Java/Spring Boot examples.

Overview¶

Capabilities are named services that agents register with the mesh. When an agent declares a capability, other agents can discover and use it through dependency injection. Multiple agents can provide the same capability with different implementations.

Capability Selector Syntax¶

MCP Mesh uses a unified syntax for selecting capabilities throughout the framework. This same pattern appears in dependencies, @mesh.llm provider/filter, @mesh.route, and meshctl scaffold llm --filter.

Selector Fields¶

Field	Required	Description
`capability`	Yes*	Capability name to match
`tags`	No	Tag filters. Optional `+` (preferred) / `-` (excluded) operators
`version`	No	Semantic version constraint (e.g., `>=2.0.0`)

*When filtering by tags only (e.g., LLM tool filter), capability can be omitted.

Syntax Forms¶

Shorthand (capability name only):

dependencies=["date_service", "weather_data"]

Full form (with filters):

dependencies=[
    {"capability": "date_service"},
    {"capability": "weather_data", "tags": ["+fast", "-deprecated"]},
    {"capability": "api_client", "version": ">=2.0.0"},
]

Where This Syntax Is Used¶

Context	Example
`@mesh.tool` dependencies	`dependencies=["svc"]` or `[{"capability": "svc"}]`
`@mesh.llm` provider	`provider={"capability": "llm", "tags": ["+claude"]}`
`@mesh.llm` filter	`filter=[{"capability": "calc"}, {"tags": ["tools"]}]`
`@mesh.route` dependencies	`dependencies=[{"capability": "api", "tags": ["+v2"]}]`
`meshctl scaffold llm --filter`	`--filter '[{"capability": "x"}]'`

Tag Operators¶

Prefix	Meaning	Example
(none)	Required	`"api"`
`+`	Preferred	`"+fast"`
`-`	Excluded	`"-deprecated"`

Selector Logic (AND/OR)¶

Syntax	Semantics
`tags: ["a", "b", "c"]`	a AND b AND c (all required)
`tags: ["+a", "+b"]`	Prefer a, prefer b (neither required)
`tags: ["a", "-x"]`	Must have a, must NOT have x
`tags: ["a", ["b", "c"]]`	a AND (b OR c) - tag-level OR
`tags: [["a"], ["b"]]`	a OR b (full OR)
`[{tags:["a"]}, {tags:["b"]}]`	a OR b (multiple selectors - LLM filter)

Tag-Level OR:

Use a nested array in tags for an OR group, and mark the alternative you prefer with +:

dependencies=[
    # Require addition AND (python OR typescript), preferring python
    {"capability": "math", "tags": ["addition", ["+python", "typescript"]]},
]

A provider qualifies if it has addition and at least one of python or typescript; if none qualifies, the dependency is unresolved. The alternatives are not tried in order: the registry scores every qualifying provider and the highest score wins, so +python is what makes the python implementation preferred (a matched + alternative scores more than a plain one).

See meshctl man tags for detailed tag matching behavior.

Declaring Capabilities¶

@app.tool()
@mesh.tool(
    capability="weather_data",           # Capability name
    description="Provides weather info", # Human-readable description
    version="1.0.0",                     # Semantic version
    tags=["weather", "current", "api"],  # Tags for filtering
)
def get_weather(city: str) -> dict:
    return {"city": city, "temp": 72, "conditions": "sunny"}

Capability Resolution¶

When an agent requests a dependency, the registry resolves it by:

Name matching: Find agents providing the requested capability
Tag filtering: Apply tag constraints (if specified)
Version constraints: Check semantic version compatibility
Tiebreaker: Select exactly one winner from the survivors — highest tag score, then highest version, then agent ID

The registry does not load balance: it picks a single deterministic winner and holds it until the topology changes. See Tiebreaker.

Multiple Implementations¶

Multiple agents can provide the same capability:

# Agent 1: OpenWeather implementation
@mesh.tool(
    capability="weather_data",
    tags=["weather", "openweather", "free"],
)
def openweather_data(city: str): ...

# Agent 2: Premium weather implementation
@mesh.tool(
    capability="weather_data",
    tags=["weather", "premium", "accurate"],
)
def premium_weather_data(city: str): ...

Consumers can select implementations using tag filters:

@mesh.tool(
    dependencies=[{"capability": "weather_data", "tags": ["+premium"]}],
)
def get_forecast(weather: mesh.McpMeshTool = None): ...

Dependency Declaration¶

Simple (by name)¶

@mesh.tool(
    dependencies=["date_service", "weather_data"],
)
def my_tool(date: mesh.McpMeshTool = None, weather: mesh.McpMeshTool = None):
    pass

Advanced (with filters)¶

@mesh.tool(
    dependencies=[
        {"capability": "date_service"},
        {"capability": "weather_data", "tags": ["+accurate", "-deprecated"]},
    ],
)
def my_tool(date: mesh.McpMeshTool = None, weather: mesh.McpMeshTool = None):
    pass

Capability Naming Conventions¶

Pattern	Example	Use Case
`noun_noun`	`weather_data`	Data providers
`verb_noun`	`get_time`	Action services
`domain_action`	`auth_validate`	Domain-specific
`service`	`llm`	Generic services

A capability name is one or more dot-separated segments, each matching ^[a-zA-Z][a-zA-Z0-9_-]*$ — a leading letter followed by letters, digits, underscores, or hyphens, with no leading, trailing, or consecutive dots. Single-segment names like weather_data are the common case; dot-namespacing (media.caption, billing.v2.invoice) is the convention for grouping related capabilities under a service prefix. meshctl list --services and the meshui agent-detail view render dotted capabilities as grouped services — display-only, derived entirely from the name.

Versioning¶

Capabilities support semantic versioning:

@mesh.tool(
    capability="api_client",
    version="2.1.0",
)
def api_v2(): ...

Consumers can specify version constraints:

dependencies=[{"capability": "api_client", "version": ">=2.0.0"}]