Package com.tnsai.annotations

Annotation Interface MCPTool

@Documented
@Retention(RUNTIME)
@Target({})
public @interface MCPTool

Configures MCP (Model Context Protocol) tool action execution.

This annotation provides configuration for MCP_TOOL type actions, defining the MCP server connection and tool invocation parameters.

Usage with @Action

 @ActionSpec(
     type = ActionType.MCP_TOOL,
     description = "Access cryptocurrency data via CoinGecko",
     mcpTool = @MCPTool(
         serverUrl = "https://mcp.coingecko.com/mcp",
         toolName = "get_coin_price",
         apiKeyEnv = "COINGECKO_API_KEY"
     )
 )
 public CoinPrice getCoinPrice(String coinId) {
     return null; // Executed via MCP
 }
 

MCP Protocol

MCP (Model Context Protocol) is a standard for LLM-tool interaction:

• Server provides tool definitions via /tools endpoint
• Client invokes tools via /invoke endpoint
• Supports both stdio and HTTP transports

Transport Types

Type	Description	serverUrl Format
HTTP	HTTP/SSE transport	https://server.com/mcp
STDIO	Local process	stdio:///path/to/server
WSS	WebSocket	wss://server.com/mcp

Author:

TnsAI Team

See Also:

• invalid reference

  Action

• ActionType.MCP_TOOL

Required Element Summary

Required Elements

Modifier and Type	Required Element	Description
String	serverUrl	MCP server URL.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String	apiKeyEnv	Environment variable for API key authentication.
boolean	cacheToolDefinitions	Whether to cache tool definitions.
int	cacheTtlSeconds	Cache TTL in seconds.
Header[]	headers	Custom headers for HTTP transport.
int	retryBackoffMs	Backoff time between retries in ms.
int	retryCount	Maximum retries on connection failure.
String	returnKey	Parameter name to inject the MCP tool response into.
String[]	stdioArgs	Arguments for stdio command.
String	stdioCommand	Command for stdio transport.
String[]	stdioEnv	Environment variables for stdio process.
int	timeout	Request timeout in milliseconds.
String	toolName	Specific tool name to invoke.
boolean	validateParameters	Whether to validate tool parameters against schema.

Element Details

serverUrl

String serverUrl

MCP server URL.

Supports HTTP, stdio, and WebSocket transports.

Returns:

server URL

toolName

String toolName

Specific tool name to invoke.

If empty, tool name is derived from method name.

Returns:

tool name

Default:

""

apiKeyEnv

String apiKeyEnv

Environment variable for API key authentication.

Returns:

env var name

Default:

""

timeout

int timeout

Request timeout in milliseconds.

Returns:

timeout in ms

Default:

30000

headers

Header[] headers

Custom headers for HTTP transport.

Returns:

array of headers

Default:

{}

retryCount

int retryCount

Maximum retries on connection failure.

Returns:

retry count

Default:

3

retryBackoffMs

int retryBackoffMs

Backoff time between retries in ms.

Returns:

backoff time

Default:

1000

cacheToolDefinitions

boolean cacheToolDefinitions

Whether to cache tool definitions.

When true, tool schema is fetched once and cached.

Returns:

true to enable caching

Default:

true

cacheTtlSeconds

int cacheTtlSeconds

Cache TTL in seconds.

-1 means cache forever (until restart).

Returns:

cache TTL

Default:

3600

validateParameters

boolean validateParameters

Whether to validate tool parameters against schema.

Returns:

true to validate

Default:

true

stdioCommand

String stdioCommand

Command for stdio transport.

Example: "npx -y @modelcontextprotocol/server-filesystem"

Returns:

stdio command

Default:

""

stdioArgs

String[] stdioArgs

Arguments for stdio command.

Returns:

command arguments

Default:

{}

stdioEnv

String[] stdioEnv

Environment variables for stdio process.

Format: "KEY=value"

Returns:

env vars

Default:

{}

returnKey

String returnKey

Parameter name to inject the MCP tool response into.

When specified, the response from the MCP tool call is injected into the method parameter with this name, allowing post-processing in the method body.

 @ActionSpec(
     type = ActionType.MCP_TOOL,
     mcpTool = @MCPTool(
         serverUrl = "https://mcp.example.com",
         toolName = "get_data",
         returnKey = "mcpResult"
     )
 )
 public Data fetchData(String query, Object mcpResult) {
     // mcpResult contains the MCP tool response
     Data data = (Data) mcpResult;
     data.setSource("MCP");
     return data;
 }
 

Returns:

parameter name for response injection, empty if not used

Default:

""