skill → shells out to an authed CLI
# The CLI already did the OAuth dance,
# stores & refreshes the token for us.
import subprocess, json

def search_open_data(query):
    out = subprocess.run(
        ["ckanapi", "action", "package_search",
         f"q={query}", "--remote", PORTAL],
        capture_output=True, text=True,
    )
    return json.loads(out.stdout)["result"]

• No secrets in the agent or prompt
• Token refresh handled by the tool
• Same path your team uses by hand
• The Skill is just orchestration over a trusted binary

server.pyfrom fastmcp import FastMCP

mcp = FastMCP(name="OpenDataServer")

@mcp.tool
def find_datasets(query: str, limit: int = 5) -> list[dict]:
    """Search the open-data catalogue for datasets."""
    hits = catalogue.search(query, k=limit)
    return [d.summary() for d in hits]

if __name__ == "__main__":
    mcp.run()

• Type hints → JSON schema, automatically
• Docstring → the tool's description
• Return value → handed back to the model
• FastMCP: the most-used Python MCP framework (Prefect / J. Lowin).

app/api/[transport]/route.tsimport { createMcpHandler } from 'mcp-handler';
import { knowledgeSearch } from '@/lib/ai/tools/knowledge-search';

// existing AI SDK tool, scoped + opinionated
const sanihub = knowledgeSearch({
  tenantId: 'sanihub',
  allowedTenants: ['sanihub'],   // tenant gating
  enableReranking: true,         // server-side rerank
});

const handler = createMcpHandler((server) => {
  server.registerTool('knowledgeSearch',
    { description: sanihub.description,
      inputSchema: sanihub.inputSchema.shape },
    async (args) => ({ content: [{ type: 'text',
      text: await sanihub.execute(args) }] }));
});
export { handler as GET, handler as POST };

any AI SDK client connectsimport { experimental_createMCPClient
  as createMCPClient } from 'ai';

const mcp = await createMCPClient({
  transport: { type: 'sse',
    url: 'https://washai.org/api/mcp',
    headers: { Authorization: `Bearer ${tok}` }}});

const tools = await mcp.tools();   // MCP → AI SDK
await generateText({ model, tools, prompt });

• Reuse the app's tools, zero rewrite
• One endpoint extends Sanihub to any client

one tool, expanded into context{
  "name": "get_dataset_resource_view_v3",
  "description": "Return a resource view ...",
  "inputSchema": {
    "type": "object",
    "properties": {
      "dataset_id": {"type":"string","description":"..."},
      "resource_id":{"type":"string","description":"..."},
      "view_id":   {"type":"string","description":"..."},
      "include_draft":{"type":"boolean"},
      "format":   {"enum":["json","csv","xml"]}
    },
    "required":["dataset_id","resource_id"]
  }
}   # × 200 tools …

Context window used by tool schemas:

• Higher cost & latency, every call
• Model confusion → wrong tool picks

the only tool the client sees up front@mcp.tool
def search_tools(need: str) -> list[ToolCard]:
    """Find the right tool for a task, by intent."""
    return registry.rank(need)        # keyword + embeddings

# agent: search_tools("query a CSV resource")
#  → returns 2–3 candidates, full schema on demand

Context window used by tool schemas:

• 200 tools become 1 entry point
• Schemas load just-in-time
• ~50k → ~2–3k tokens of overhead

FastMCP's tool search / code mode ships this pattern out of the box.

any REST API → MCP serverimport httpx
from fastmcp import FastMCP

client = httpx.AsyncClient(base_url="https://api.example.com")
spec   = httpx.get("https://api.example.com/openapi.json").json()

mcp = FastMCP.from_openapi(
    openapi_spec=spec,
    client=client,          # auth lives on the client
    name="CatalogueAPI",
)
mcp.run()

• Every endpoint becomes a tool by default
• RouteMap to include / exclude / retag

one intent-shaped tool, heavy lifting hidden@mcp.tool
def find_knowledge(question: str) -> list[Passage]:
    """Answer-ready evidence for a question."""
    hits   = hybrid_search(question)      # BM25 + vectors
    ranked = cross_encoder_rerank(question, hits)
    ranked = dedupe(ranked)
    return [trim(p) for p in ranked[:5]]  # small, clean

• Skill = client, MCP = server. Lightweight & personal vs shared & agentic.
• Let the agent drive a CLI. A composable surface, auth included.
• Watch the token bill. 200 schemas can eat half your window.

• Expose one search_tools. Discovery beats dumping.
• Re-expose what you built. mcp-handler wraps existing app tools, like Sanihub↗.
• Gate & price it. Auth, rate limits, and a budget on server-side AI.