# Agent ecosystem integration

How TnsAI fits into the wider agent + tooling landscape: which
protocols TnsAI speaks natively, how it's consumed by IDEs and
other agent runtimes, and what conventions help LLMs use the
framework directly.

There are two integration directions to keep separate in your head:

| Direction | Who | How |
|---|---|---|
| **TnsAI consuming** external tools | TnsAI agents calling MCP servers, web APIs, sub-LLMs | `tnsai-mcp` client + `@MCPTool` + `@WebService` annotations |
| **TnsAI being consumed** by external agents | Cursor / Claude Code / Continue / OpenAI Agents SDK calling TnsAI | `tnsai-mcp` **server** — exposes any TnsAI tool as an MCP tool |

Most of this guide covers the second direction (TnsAI as a server)
because it's the underdocumented half — for TnsAI as MCP **client**
see [MCP / Client](../mcp/client.md).

---

## TnsAI as an MCP server

`tnsai-mcp` ships a full Model Context Protocol server that wraps
any TnsAI POJO toolkit (the 63 shipped toolkits in `tnsai-tools`,
your own `@Tool`-bearing POJOs, or both) and exposes them over
HTTP/SSE so any MCP-compatible client (Claude Code, Cursor,
Continue.dev, the official MCP Inspector, your own agent runtime)
can call them.

### Minimal example — explicit toolkits, on port 3000

```java
import com.tnsai.enums.BuiltInTool;
import com.tnsai.mcp.server.HttpMcpServer;
import com.tnsai.mcp.server.TnsAIToolProvider;

HttpMcpServer server = HttpMcpServer.builder()
    .port(3000)
    .addToolProvider(TnsAIToolProvider.fromPojos(
        BuiltInTool.WEB_SEARCH_TOOLS.instantiate(),
        BuiltInTool.UTILITY_TOOLS.instantiate(),
        BuiltInTool.PDF_TOOLS.instantiate()
    ))
    .build();

server.start();
// Server is now serving MCP at http://localhost:3000/mcp
// Stop with: server.stop();
```

`TnsAIToolProvider.fromPojos(...)` wraps every `@Tool`-annotated method on
each POJO into an MCP tool definition. There is no global registry to
enumerate — you pick which toolkits to expose explicitly. This is also
the recommended path when exposing TnsAI to external agents: surface a
deliberate subset, not the whole catalogue.

### Mixing custom POJOs

```java
HttpMcpServer server = HttpMcpServer.builder()
    .port(3000)
    .addToolProvider(TnsAIToolProvider.fromPojos(
        BuiltInTool.UTILITY_TOOLS.instantiate(),
        new MyDomainTools(),
        new MyAnalyticsTools()
    ))
    .build();
```

### Builder reference

| Method | Default | Purpose |
|---|---|---|
| `.port(int)` | `3000` | HTTP listen port |
| `.path(String)` | `/mcp` | URL path mount point |
| `.serverName(String)` | `"TnsAI MCP Server"` | Identity returned in MCP `initialize` |
| `.serverVersion(String)` | TnsAI's | Version returned in MCP `initialize` |
| `.sessionTtl(Duration)` | `Duration.ofMinutes(30)` | Idle session expiry |
| `.addToolProvider(ToolProvider)` | — | Register a `ToolProvider`. Multiple allowed. |
| `.addResourceProvider(ResourceProvider)` | — | Same, for MCP resources |
| `.addPromptProvider(PromptProvider)` | — | Same, for MCP prompts |

All providers are interfaces — implement them yourself if you want
to expose data or prompts that aren't TnsAI tools. The
`TnsAIToolProvider` is just the prebuilt adapter for the POJO toolkit
case; for runtime-defined tools (e.g. plugin-loaded), use
`TnsAIToolProvider.fromDynamic(DynamicToolMethod...)` instead.

---

## Consuming TnsAI from Claude Code

Add the running TnsAI server to your Claude Code MCP config. In
`~/.claude/mcp_servers.json` (or wherever Claude Code stores its
MCP config — paths vary by platform):

```json
{
  "mcpServers": {
    "tnsai": {
      "transport": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

Restart Claude Code. The TnsAI tools appear in the MCP tool
inspector and Claude can call them like any other MCP tool.

For production, expose the MCP server behind authentication and
use HTTPS. The HTTP server is a thin wrapper over the JDK's
built-in `HttpServer`; bring your own reverse proxy for TLS +
auth.

## Consuming TnsAI from Cursor / Continue.dev

Both Cursor and Continue.dev support MCP servers via similar JSON
configurations. Point them at the same `http://localhost:3000/mcp`
endpoint (or a remote URL). The TnsAI tools will appear as
first-class entries in the IDE's tool palette.

Tested clients:

- **Claude Code** ✓ (canonical reference)
- **Cursor** ✓
- **Continue.dev** ✓
- **MCP Inspector** ✓ (the official `npx @modelcontextprotocol/inspector` tool)
- **Any HTTP MCP client** — the wire protocol follows the spec at
  [modelcontextprotocol.io](https://modelcontextprotocol.io)

---

## OpenAI function-calling format

TnsAI agents speak OpenAI's function-calling format internally —
when your agent uses `OpenAIClient`, `AnthropicClient`, etc., the
LLM provider's tool-call format is translated to and from the
common `ChatResponse.ToolCall` shape automatically. You don't need
to do anything special.

If you want to inspect the JSON-Schema fragments TnsAI sends to LLM
providers (e.g. for debugging, or to feed an external hosted
assistant), build a temporary agent and read the dispatcher's
registry:

```java
import com.tnsai.agents.AgentBuilder;
import com.tnsai.enums.BuiltInTool;
import com.tnsai.tools.method.ToolMethodRegistry;

Agent inspector = AgentBuilder.create()
    .role(myRole)
    .builtInTools(BuiltInTool.WEB_SEARCH_TOOLS, BuiltInTool.UTILITY_TOOLS)
    .toolPojos(new MyDomainTools())
    .build();

ToolMethodRegistry registry = inspector.getToolMethodDispatcher().registry();
for (var tool : registry.allMethods()) {
    System.out.println(tool.name() + " — schema: " + tool.schema());
}
```

The same registry powers internal tool-call dispatch — there's no
separate code path for "external" vs "internal" tool schemas.

---

## llms.txt + AGENTS.md conventions in your own project

If you're publishing a service or library that uses TnsAI, two
conventions are worth adopting:

- **`/llms.txt`** at your service root — short markdown index of
  what your service is and where the docs live. The TnsAI site
  itself uses this; see [tnsai.dev/llms.txt](https://tnsai.dev/llms.txt)
  for the format. Spec at [llmstxt.org](https://llmstxt.org).
- **`AGENTS.md`** at your repo root — operating instructions for
  AI coding agents working in your codebase. The TnsAI repos
  themselves do this; see
  [github.com/TnsAI-Framework/TnsAI/blob/main/AGENTS.md](https://github.com/TnsAI-Framework/TnsAI/blob/main/AGENTS.md)
  for an example. Convention page at [agents.md](https://agents.md).

Both files are static markdown — no runtime cost — and let any
agent ramp into your project before it sees the code.

---

## See also

- [MCP / Client](../mcp/client.md) — TnsAI consuming external MCP tools
- [MCP / Server](../mcp/server.md) — deeper reference for the MCP server
- [MCP / Transports](../mcp/transports.md) — Stdio, SSE, HTTP options
- [Tools / Catalog](../capabilities/tools/catalog.md) — the 63 POJO toolkits you can expose
- [SCOP](scop.md) — bridge to the [SCOP framework](https://scop-framework.netlify.app/) for declarative system prompts + LLM fallback