DEV Community: NeuroLink AI

MCP Server Tutorial: Build Your Own AI Tools in 30 Minutes

NeuroLink AI — Sat, 04 Jul 2026 04:02:39 +0000

You will build an MCP server with three custom AI tools in 30 minutes: a database query tool, a notification tool, and a file operations tool. By the end of this tutorial, you will have a working MCP server with Zod-validated tool schemas, rate limiting, circuit breaker resilience, and full integration with the NeuroLink SDK for end-to-end AI tool calling.

The Model Context Protocol (MCP) decouples your business logic from your AI orchestration layer. Instead of hardcoding tool logic into your application, you define tools on a server that any AI agent can discover and execute at runtime. Now you will set up the server and build your first tool.

What is the Model Context Protocol?

MCP standardizes how AI models discover and execute tools. The protocol defines a clear lifecycle: a server registers tools with their schemas, an AI agent discovers those tools at connection time, the model decides when to call a tool based on the user's request, the server executes the tool logic, and the result flows back to the model for incorporation into the final response.

sequenceDiagram
    participant U as User
    participant A as AI Agent
    participant M as MCP Server
    participant T as Tool Implementation

    U->>A: Ask question
    A->>M: Discover available tools
    M-->>A: Tool list with schemas
    A->>A: LLM decides to call tool
    A->>M: Execute tool with params
    M->>T: Run tool logic
    T-->>M: Return result
    M-->>A: Tool result
    A-->>U: Final answer using tool data

The key insight is separation of concerns. Your MCP server encapsulates business logic -- database queries, API calls, file operations -- behind a clean tool interface. The AI agent does not need to know how the database works or how notifications are sent. It just calls the tool with the parameters the schema defines.

This pattern has several practical benefits:

Reusability: The same MCP server can serve multiple AI agents, different models, and different applications.
Testability: Tools have defined inputs and outputs, making them easy to unit test in isolation.
Security: Tool execution happens server-side where you control access, rate limiting, and audit logging.
Discovery: Agents automatically learn what tools are available and how to call them.

Step 1 -- Create an MCP Server

Start by creating a server using the createMCPServer() factory function. The server needs an ID, title, description, and category.

import { createMCPServer } from "@juspay/neurolink";

const server = createMCPServer({
  id: "my-business-tools",
  title: "Business Tools Server",
  description: "Custom tools for business operations",
  category: "business",
  version: "1.0.0",
});

console.log("Server created:", server.id);
console.log("Category:", server.category); // "business"

The category field classifies your server for discovery and organization. NeuroLink supports the following categories: aiProviders, frameworks, development, business, content, data, integrations, automation, analysis, and custom. Choose the one that best describes your tools' purpose.

The server object is a lightweight container that holds tool registrations and provides methods for validation and execution. It does not start an HTTP server or listen on a port. It is a logical grouping of tools that can be embedded in any application, exposed over HTTP, or used directly in-process.

Step 2 -- Register Tools

Tools are the core of your MCP server. Each tool needs a name, a description (used by the LLM to decide when to call it), a parameters schema (defined with Zod for runtime validation and type inference), and an execute function that contains your business logic.

import { z } from "zod";

// Tool 1: Database query tool
server.registerTool({
  name: "queryDatabase",
  description: "Execute a read-only SQL query against the analytics database",
  parameters: z.object({
    query: z.string().describe("SQL SELECT query"),
    limit: z.number().optional().default(100).describe("Max rows"),
  }),
  execute: async (params) => {
    const { query, limit } = params;
    if (!query.trim().toUpperCase().startsWith("SELECT")) {
      return { success: false, error: "Only SELECT queries allowed" };
    }
    // Use a read-only database role for defense-in-depth
    const results = await db.query(`${query} LIMIT $1`, [limit]);
    return { success: true, data: results, rowCount: results.length };
  },
});

// Tool 2: Send notification tool
server.registerTool({
  name: "sendNotification",
  description: "Send a notification to a Slack channel or email",
  parameters: z.object({
    channel: z.enum(["slack", "email"]).describe("Notification channel"),
    recipient: z.string().describe("Channel ID or email address"),
    message: z.string().describe("Notification message"),
  }),
  execute: async (params) => {
    if (params.channel === "slack") {
      await slackClient.postMessage(params.recipient, params.message);
    } else {
      await emailClient.send(params.recipient, "AI Notification", params.message);
    }
    return { success: true, channel: params.channel };
  },
});

// Tool 3: File operations
server.registerTool({
  name: "readFile",
  description: "Read the contents of a file from the project directory",
  parameters: z.object({
    path: z.string().describe("Relative file path"),
  }),
  execute: async (params) => {
    const PROJECT_DIR = path.resolve(process.cwd());
    const safePath = path.resolve(PROJECT_DIR, params.path);
    if (!safePath.startsWith(PROJECT_DIR)) {
      return { success: false, error: "Path traversal detected" };
    }
    const content = await fs.readFile(safePath, "utf-8");
    return { success: true, content, size: content.length };
  },
});

Security: This example allows the LLM to submit arbitrary SELECT queries. In production, use a read-only database role, restrict queries to an allowlist of approved tables, and consider a query builder like Knex or Drizzle instead of raw SQL. The startsWith("SELECT") check is a minimal guard — it does not prevent data exfiltration via UNION or subqueries. Always use parameterized queries for user-supplied values (like limit), and never interpolate untrusted input into SQL identifiers (table or column names).
{: .prompt-warning }

A few important design principles for tool definitions:

Descriptions matter more than names. The LLM reads the description to decide when to call the tool. Write descriptions that clearly state what the tool does, what inputs it expects, and what it returns. A vague description leads to incorrect tool selection.

Zod schemas enforce contracts. The parameters schema defines the exact shape of the input the tool accepts. Zod validates inputs at runtime, so malformed parameters from the LLM are caught before your business logic runs. Use .describe() on each field to give the LLM hints about expected values.

Execute functions should be defensive. Always validate inputs beyond what Zod checks. In the database tool example, we verify the query starts with SELECT even though the description says "read-only" -- because LLMs do not always follow instructions perfectly.

Note: Tool names should be camelCase and descriptive. The LLM uses the name alongside the description to determine when a tool is appropriate. Avoid generic names like "doThing" or "process" -- specific names like "queryDatabase" or "sendNotification" give the model clearer intent signals.
{: .prompt-info }

Step 3 -- Validate Tools

Before using your tools in production, validate them to ensure they follow proper patterns. The validateServerTools() function checks all registered tools for completeness and correctness.

import { validateServerTools, getServerInfo } from "@juspay/neurolink";

// Validate all tools
const validation = await validateServerTools(server);

if (!validation.isValid) {
  console.error("Invalid tools:", validation.invalidTools);
  console.error("Errors:", validation.errors);
  process.exit(1);
}

// Get server info
const info = getServerInfo(server);
console.log(`Server: ${info.title}`);
console.log(`Tools registered: ${info.toolCount}`);
console.log(`Category: ${info.category}`);

Validation checks include: tool names are non-empty strings, descriptions exist and are meaningful, execute functions are callable, and parameter schemas are valid Zod objects. Running validation at startup catches configuration errors early, before any user request hits a broken tool.

The getServerInfo() function provides a summary of the server's state: how many tools are registered, what category it belongs to, and its version. This is useful for health check endpoints and operational dashboards.

Step 4 -- Use Tools with NeuroLink

Now connect your MCP tools to the NeuroLink SDK so that LLMs can discover and call them during generation.

import { NeuroLink } from "@juspay/neurolink";
import { tool } from "ai";
import { z } from "zod";

const neurolink = new NeuroLink();

// Convert MCP tools to AI SDK format for use with generate/stream
const aiTools = {
  queryDatabase: tool({
    description: "Execute a read-only SQL query against the analytics database",
    parameters: z.object({
      query: z.string().describe("SQL SELECT query"),
      limit: z.number().optional().default(100),
    }),
    execute: async (params) => {
      // Delegate to MCP server tool
      return server.tools["queryDatabase"].execute(params);
    },
  }),
  sendNotification: tool({
    description: "Send a notification to a Slack channel or email",
    parameters: z.object({
      channel: z.enum(["slack", "email"]),
      recipient: z.string(),
      message: z.string(),
    }),
    execute: async (params) => {
      return server.tools["sendNotification"].execute(params);
    },
  }),
};

// Use tools in generation
const result = await neurolink.generate({
  input: {
    text: "How many orders did we process last week? Send a summary to #analytics on Slack.",
  },
  provider: "openai",
  model: "gpt-4o",
  tools: aiTools,
});

console.log(result.content);

When you pass tools to neurolink.generate(), the LLM receives the tool schemas as part of its system context. It then decides whether to call tools based on the user's request. In this example, the model would likely call queryDatabase to get order counts, then call sendNotification to post the summary to Slack, and finally synthesize a natural language response.

The delegation pattern (AI tool wrapping MCP server tool) keeps your MCP server as the single source of truth for tool logic. The AI SDK tools are thin wrappers that forward execution to the MCP server. This means you can update tool logic in one place and all consumers get the update automatically.

Note: The tools option in generate() accepts tools in the AI SDK format. The MCP server's registerTool() uses a slightly different shape. The wrapper pattern shown above bridges the two formats cleanly. In the future, NeuroLink will support direct MCP tool passthrough.
{: .prompt-info }

Step 5 -- Add Rate Limiting and Circuit Breaking

Production MCP servers need protection against abuse and cascading failures. NeuroLink provides built-in rate limiting and circuit breaking specifically designed for MCP tool execution.

import {
  HTTPRateLimiter,
  MCPCircuitBreaker,
  DEFAULT_RATE_LIMIT_CONFIG,
} from "@juspay/neurolink";

// Rate limit: 100 requests per minute
const rateLimiter = new HTTPRateLimiter({
  ...DEFAULT_RATE_LIMIT_CONFIG,
  maxRequests: 100,
  windowMs: 60000,
});

// Circuit breaker: Open after 5 failures, reset after 30s
const circuitBreaker = new MCPCircuitBreaker({
  failureThreshold: 5,
  resetTimeoutMs: 30000,
});

The rate limiter prevents any single client from overwhelming your tools. At 100 requests per minute, a runaway agent loop would be throttled before it racks up significant costs or overwhelms your database.

The circuit breaker monitors failure rates for tool execution. After five consecutive failures (a database connection timeout, an API outage, etc.), the circuit opens and immediately returns errors without attempting execution. After 30 seconds, the circuit enters a half-open state and allows a single test request through. If it succeeds, the circuit closes and normal operation resumes. If it fails, the circuit stays open for another 30 seconds.

Together, rate limiting and circuit breaking give your MCP server production-grade resilience without complex custom implementation.

Tool validation deep dive

The validateTool() function provides fine-grained validation for individual tools, useful during development and testing:

import { validateTool } from "@juspay/neurolink";

const isValid = validateTool({
  name: "myTool",
  description: "Does something useful",
  execute: async (params) => ({ result: "ok" }),
});

console.log("Valid:", isValid); // true

Validation checks cover several categories:

Name validation: Names must be non-empty strings, ideally camelCase.
Description validation: Descriptions must exist and provide meaningful context for the LLM.
Execute validation: The execute field must be a callable async function.
Parameter validation: If parameters are provided, they must be valid Zod schemas with correct types and descriptions.

Running validation in your CI/CD pipeline ensures that no malformed tool definitions ship to production.

Architecture overview

Here is the complete architecture of an MCP server integrated with NeuroLink:

flowchart TD
    A[createMCPServer] --> B[MCP Server Instance]
    B --> C[registerTool x3]
    C --> D[validateServerTools]
    D --> E{Valid?}
    E -->|Yes| F[NeuroLink SDK]
    E -->|No| G[Fix Errors]
    G --> C
    F --> H[generate/stream with tools]
    H --> I[LLM calls tools]
    I --> J[Tool executes]
    J --> K[Result returned to LLM]
    K --> L[Final response]

    M[Rate Limiter] --> I
    N[Circuit Breaker] --> I

The flow is straightforward: create a server, register tools, validate them, and connect to NeuroLink. During generation, the LLM calls tools as needed, with rate limiting and circuit breaking protecting every execution. Results flow back to the LLM for synthesis into a final response.

Testing Your MCP Tools

Testability is one of the strongest benefits of the MCP pattern. Because tools have defined inputs and outputs, you can unit test them without any AI involvement:

// Unit test
const result = await server.tools["queryDatabase"].execute({
  query: "SELECT COUNT(*) FROM orders WHERE date > '2025-01-01'",
  limit: 1,
});
assert(result.success === true);

For integration testing, run the full flow through neurolink.generate() with your tools and verify that the model correctly identifies when to call each tool and how to interpret the results. Mock your external dependencies (database, Slack, email) to keep integration tests fast and deterministic.

Test edge cases thoroughly: What happens when the database returns zero rows? When the Slack API is down? When the file does not exist? Each tool should return structured error responses that the LLM can interpret gracefully, rather than throwing unhandled exceptions.

// Edge case test: invalid SQL
const invalidResult = await server.tools["queryDatabase"].execute({
  query: "DROP TABLE orders",
  limit: 1,
});
assert(invalidResult.success === false);
assert(invalidResult.error === "Only SELECT queries allowed");

// Edge case test: missing file
try {
  await server.tools["readFile"].execute({
    path: "./nonexistent.txt",
  });
  assert.fail("Should have thrown");
} catch (error) {
  assert(error.code === "ENOENT");
}

Tip: Always return structured error objects from your tools rather than throwing exceptions. The LLM can interpret a { success: false, error: "..." } response and adjust its approach, but an unhandled exception terminates the tool call chain entirely.
{: .prompt-tip }

Real-World MCP Server Patterns

Beyond the basics, here are patterns we see in production MCP deployments:

Composite tools wrap multiple operations into a single tool call. Instead of the LLM calling "queryDatabase" and then "sendNotification" separately, a "generateAndSendReport" tool handles the entire workflow internally. This reduces the number of tool calls and the chance of the LLM making intermediate mistakes.

Parameterized permissions restrict tool access based on the calling context. A tool can check the user's role before executing sensitive operations, returning a permission error if the caller lacks the required access level.

// Authentication middleware for MCP tool execution
function withAuth(tool: MCPTool, requiredRole: string): MCPTool {
  return {
    ...tool,
    execute: async (params, context) => {
      const user = await verifyToken(context.headers?.authorization);
      if (!user || !user.roles.includes(requiredRole)) {
        return { success: false, error: "Unauthorized: insufficient permissions" };
      }
      return tool.execute(params, { ...context, user });
    },
  };
}

// Usage
server.registerTool(withAuth(queryDatabaseTool, "analyst"));
server.registerTool(withAuth(sendNotificationTool, "admin"));

Caching layers store frequent tool results for reuse. If ten users ask "How many orders this month?" in a minute, the database tool can serve cached results instead of hitting the database ten times.

Audit logging records every tool call with its parameters, caller, timestamp, and result. This is essential for regulated industries where you need to prove what the AI did and why.

What you built

You built a fully functional MCP server with three validated tools, rate limiting, circuit breaker resilience, and end-to-end NeuroLink integration. Your tools are discoverable, testable, and usable by any AI agent without code changes.

Continue with these related tutorials:

Building a RAG Application for exposing your RAG pipeline as an MCP tool
Structured Output from LLMs for validating tool outputs with Zod schemas
Building a Slack Bot with AI for connecting MCP tools to a Slack bot

Related posts:

Getting Started with NeuroLink: Your First AI App in 5 Minutes

NeuroLink AI — Sat, 04 Jul 2026 04:02:27 +0000

You've heard about AI SDKs but aren't sure where to start. Let's fix that.

Imagine you want to add AI to your app -- maybe a chatbot, maybe a smart search feature. You might think you need days of setup, a PhD in machine learning, and three different API accounts. The truth is, you can get a working AI call running in under 5 minutes with NeuroLink. No prior AI experience needed.

NeuroLink (@juspay/neurolink) handles all the complicated provider stuff behind the scenes. You just write a few lines of TypeScript, and it works with any major AI provider -- OpenAI, Google, Anthropic, and more.

In this post, you will learn:

How to install and configure NeuroLink
How to make your first AI generation call
How to switch providers with a single line change
How to add streaming for real-time output

flowchart LR
    A["npm install<br/>@juspay/neurolink"] --> B["Configure<br/>.env API key"]
    B --> C["Import &<br/>Instantiate"]
    C --> D["Call<br/>generate()"]
    D --> E["AI Response"]
    style A fill:#0f4c75,stroke:#1b262c,color:#fff
    style B fill:#0f4c75,stroke:#1b262c,color:#fff
    style C fill:#3282b8,stroke:#1b262c,color:#fff
    style D fill:#3282b8,stroke:#1b262c,color:#fff
    style E fill:#00b4d8,stroke:#1b262c,color:#fff

Prerequisites

Before you begin, make sure you have the following:

Node.js >= 20.18.1 -- NeuroLink requires a modern Node.js runtime. Check your version with node --version.
npm >= 10.0.0 or pnpm >= 8.0.0 -- Either package manager works. This tutorial uses npm, but pnpm commands are identical.
An API key from at least one supported provider -- OpenAI, Anthropic, Google, AWS, or any of the 13 supported providers. If you do not have one yet, OpenAI and Google AI Studio both offer quick signup with free trial credits.
Basic TypeScript/JavaScript knowledge -- NeuroLink is TypeScript-native, but you can use it from plain JavaScript too.

Tip: Not sure which provider to pick? Think of it like choosing a phone carrier -- they all do the same basic thing, just with different pricing. OpenAI (gpt-4o) has the biggest community, while Google AI Studio (gemini-2.5-flash) lets you get started for free.
{: .prompt-tip }

Installation

Step 1: Create a New Project

Start with a fresh directory and initialize a Node.js project configured for ES modules:

mkdir my-ai-app && cd my-ai-app
npm init -y

Update your package.json to enable ES module support:

{
  "name": "my-ai-app",
  "type": "module",
  "scripts": {
    "start": "npx tsx src/index.ts"
  }
}

Step 2: Install NeuroLink

Install the SDK with a single command:

npm install @juspay/neurolink

If you are using TypeScript (recommended), also install tsx for running TypeScript directly:

npm install -D tsx typescript

Step 3: Create a Minimal tsconfig.json

Create a tsconfig.json at the project root:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

Step 4: Configure Your API Key

Create a .env file at the project root with your provider's API key. NeuroLink auto-loads dotenv, so no additional configuration is needed:

OPENAI_API_KEY=sk-your-key-here

# For Anthropic
ANTHROPIC_API_KEY=sk-ant-your-key-here

# For Google AI Studio
GOOGLE_AI_API_KEY=your-google-key-here

# For Google Vertex AI
VERTEX_PROJECT_ID=your-gcp-project-id

You only need one provider key to get started. Add more later when you want to explore multi-provider features.

Warning: Your .env file contains secret API keys -- treat it like a password. Never commit it to Git. Add .env to your .gitignore file right away.
{: .prompt-warning }

Your First Generate Call

Create src/index.ts and write your first AI generation:

import { NeuroLink } from '@juspay/neurolink';

const neurolink = new NeuroLink();

const result = await neurolink.generate({
  input: { text: 'Explain quantum computing in simple terms' },
  provider: 'openai',
  model: 'gpt-4o'
});

console.log(result.content);
console.log(`Tokens used: ${result.usage?.total}`);
console.log(`Response time: ${result.responseTime}ms`);

Run it:

npm start

That is it. Five lines of meaningful code, and you have a working AI application.

Understanding the API

Let us break down what each part does.

GenerateOptions -- the object you pass to generate():

Field	Type	Description
`input.text`	`string`	The prompt or question for the AI model
`provider`	`string`	Which AI provider to use (e.g., `'openai'`, `'anthropic'`, `'vertex'`)
`model`	`string`	The specific model to use (e.g., `'gpt-4o'`, `'claude-sonnet-4-5-20250929'`)
`temperature`	`number`	Creativity control: 0 = deterministic, 1 = creative (optional)
`maxTokens`	`number`	Maximum tokens in the response (optional)
`systemPrompt`	`string`	Instructions that shape the AI's behavior (optional)

GenerateResult -- the object you get back:

Field	Type	Description
`content`	`string`	The AI's response text
`provider`	`string`	Which provider was used
`model`	`string`	Which model was used
`usage.total`	`number`	Total tokens consumed
`usage.input`	`number`	Tokens in the input prompt
`usage.output`	`number`	Tokens in the output response
`responseTime`	`number`	Time in milliseconds

Note: Token usage fields use total, input, and output -- not totalTokens or inputTokens. This is a deliberate normalization across providers.
{: .prompt-info }

Switching Providers in One Line

Here is the power of a unified SDK. The same code works with any provider -- just change the provider and model strings:

import { NeuroLink } from '@juspay/neurolink';

const neurolink = new NeuroLink();

// OpenAI
const openaiResult = await neurolink.generate({
  input: { text: 'What is machine learning?' },
  provider: 'openai',
  model: 'gpt-4o'
});

// Anthropic Claude
const anthropicResult = await neurolink.generate({
  input: { text: 'What is machine learning?' },
  provider: 'anthropic',
  model: 'claude-sonnet-4-5-20250929'
});

// Google Vertex AI
const vertexResult = await neurolink.generate({
  input: { text: 'What is machine learning?' },
  provider: 'vertex',
  model: 'gemini-3-flash'
});

// AWS Bedrock
const bedrockResult = await neurolink.generate({
  input: { text: 'What is machine learning?' },
  provider: 'bedrock',
  model: 'anthropic.claude-3-sonnet-20240229-v1:0'
});

Note: Model names and IDs in code examples reflect versions available at time of writing. Model availability, naming conventions, and pricing change frequently. Always verify current model IDs with your provider's documentation before deploying to production.
{: .prompt-info }

Every call returns the same GenerateResult type. Your application code that processes the response does not need to change at all.

flowchart TD
    A["neurolink.generate()"] --> B{"provider?"}
    B -->|"openai"| C["OpenAI GPT-4o"]
    B -->|"anthropic"| D["Claude Sonnet"]
    B -->|"vertex"| E["Gemini Flash"]
    B -->|"bedrock"| F["AWS Bedrock"]
    B -->|"ollama"| G["Local LLM"]
    C --> H["Same GenerateResult"]
    D --> H
    E --> H
    F --> H
    G --> H
    style A fill:#0f4c75,stroke:#1b262c,color:#fff
    style B fill:#3282b8,stroke:#1b262c,color:#fff
    style H fill:#00b4d8,stroke:#1b262c,color:#fff

Auto Provider Selection

If you do not want to hardcode a provider, createBestAIProvider() scans your environment variables and automatically selects the first available provider:

import { createBestAIProvider } from '@juspay/neurolink';

// Automatically uses the provider with a configured API key
const provider = await createBestAIProvider();
const result = await provider.generate({
  input: { text: 'What is machine learning?' }
});

console.log(result.content);

This is especially useful for libraries and shared modules where you do not want to assume which provider your user has configured.

All 13 Supported Providers

Here is the complete list of providers from the AIProviderName enum:

Provider	Config Key	Environment Variable
OpenAI	`openai`	`OPENAI_API_KEY`
Anthropic	`anthropic`	`ANTHROPIC_API_KEY`
Google Vertex AI	`vertex`	`VERTEX_PROJECT_ID`
AWS Bedrock	`bedrock`	AWS credentials
Azure OpenAI	`azure`	`AZURE_OPENAI_API_KEY`
Google AI Studio	`google-ai`	`GOOGLE_AI_API_KEY`
Mistral	`mistral`	`MISTRAL_API_KEY`
Ollama	`ollama`	(local, no key needed)
LiteLLM	`litellm`	`LITELLM_API_KEY`
Hugging Face	`huggingface`	`HUGGINGFACE_API_KEY`
AWS SageMaker	`sagemaker`	AWS credentials
OpenRouter	`openrouter`	`OPENROUTER_API_KEY`
OpenAI-Compatible	`openai-compatible`	Configurable

Adding Streaming

For chat interfaces and real-time applications, you want tokens to appear as they are generated rather than waiting for the complete response. Switch from generate() to stream():

import { NeuroLink } from '@juspay/neurolink';

const neurolink = new NeuroLink();

const result = await neurolink.stream({
  input: { text: 'Write a haiku about TypeScript' },
  provider: 'anthropic',
  model: 'claude-sonnet-4-5-20250929',
  systemPrompt: 'You are a creative poet.',
  temperature: 1.0
});

for await (const chunk of result.stream) {
  if ('content' in chunk) {
    process.stdout.write(chunk.content);
  }
}

The result.stream async iterator delivers text chunks as they arrive from the provider. This works identically across all 13 providers -- NeuroLink normalizes the different streaming protocols (SSE, WebSocket, HTTP chunking) into a single consistent interface.

Note: The streaming property is result.stream, not result.textStream. This is consistent across all NeuroLink streaming operations.
{: .prompt-info }

Streaming in a Web Application

If you are building a web frontend, you can pipe the stream directly to a response:

// In an Express/Hono route handler
app.post('/chat', async (req, res) => {
  const neurolink = new NeuroLink();
  const result = await neurolink.stream({
    input: { text: req.body.message },
    provider: 'openai',
    model: 'gpt-4o'
  });

  res.setHeader('Content-Type', 'text/event-stream');
  for await (const chunk of result.stream) {
    res.write(`data: ${JSON.stringify({ text: chunk })}\n\n`);
  }
  res.end();
});

Adding a System Prompt

System prompts let you shape the AI's behavior and personality. They work with both generate() and stream():

import { NeuroLink } from '@juspay/neurolink';

const neurolink = new NeuroLink();

// A helpful coding assistant
const result = await neurolink.generate({
  input: { text: 'How do I handle errors in async/await?' },
  provider: 'openai',
  model: 'gpt-4o',
  systemPrompt: 'You are a senior TypeScript developer. Provide concise, practical answers with code examples. Always mention edge cases.',
  temperature: 0.3  // Lower temperature for more deterministic, technical answers
});

console.log(result.content);

The temperature parameter controls the creativity of the output:

0.0 -- Deterministic: always picks the most likely token. Best for factual queries, code generation, and classification.
0.5 -- Balanced: a mix of reliability and variety. Good default for most applications.
1.0 -- Creative: high variance in token selection. Best for creative writing, brainstorming, and poetry.

Provider Fallback

For production applications, you want resilience. If your primary provider has an outage, you need a fallback:

import { createAIProviderWithFallback } from '@juspay/neurolink';

const { primary, fallback } = await createAIProviderWithFallback(
  'openai',   // Primary provider
  'bedrock'   // Fallback provider
);

try {
  const result = await primary.generate({ input: { text: 'Hello!' } });
  console.log(result.content);
} catch (error) {
  const result = await fallback.generate({ input: { text: 'Hello!' } });
  console.log('Fallback:', result.content);
}

This pattern ensures your application stays available even when individual providers experience issues. You can configure as many fallback layers as you need.

What's Next

Congratulations -- you just built your first AI application! Let's recap what you accomplished:

Installed NeuroLink with npm install @juspay/neurolink
Configured a provider API key in .env
Generated your first AI response with generate()
Switched providers by changing a single string
Added streaming for real-time token delivery with stream()
Customized behavior with system prompts and temperature

That was not so scary, right? Now you have a solid foundation to build on. Here are some fun next steps depending on what interests you:

Want to build more things? Check out NeuroLink Quickstart: 10 Things You Can Build Today for ten copy-paste-ready projects
Curious about tools? Connect your AI to external tools via MCP -- see the MCP Tools Integration Guide
Want to understand the big picture? Read What is NeuroLink? The Unified AI SDK Explained
Ready for production? Deploy your AI app as an HTTP API -- see From Zero to Production

Star the NeuroLink GitHub repository, join the discussions, and let us know what you build. The npm package is available now.

Related posts:

Building AI Discord Bots with NeuroLink

NeuroLink AI — Sat, 04 Jul 2026 04:02:14 +0000

You will build a fully-featured AI Discord bot using Discord.js and NeuroLink's generation API. By the end of this tutorial, you will have slash commands, multi-turn conversations, AI-powered moderation, and production deployment -- all using NeuroLink as the AI backend.

Tip: This tutorial builds a custom Discord bot from scratch. NeuroLink does not provide a built-in Discord integration -- you will build the bot infrastructure yourself using Discord.js, with NeuroLink handling AI generation.
{: .prompt-tip }

External Dependencies

This tutorial requires several npm packages for building Discord bots:

npm install @juspay/neurolink discord.js
npm install dotenv
npm install -D typescript @types/node ts-node nodemon

Required Packages:

@juspay/neurolink - NeuroLink SDK for AI generation
discord.js (v14.x) - Discord's official JavaScript library
dotenv - Environment variable management
typescript and @types/node - TypeScript support
ts-node and nodemon - Development tools

Prerequisites

Before we begin, ensure you have the following:

Node.js 18+ installed
A Discord account with a test server where you have admin permissions
NeuroLink API key (sign up at neurolink.ink)
Required packages (see External Dependencies section above)
Basic familiarity with JavaScript/TypeScript and async/await
A code editor of your choice

Important: This tutorial uses Discord.js v14.x. If you're upgrading from v13 or earlier, review the Discord.js v14 migration guide.

Setting Up Your Discord Application

First, we need to create a Discord application and bot user through the Discord Developer Portal.

Creating the Application

Navigate to the Discord Developer Portal
Click "New Application" and give it a name (e.g., "NeuroLink Assistant")
Navigate to the "Bot" section in the left sidebar
Click "Add Bot" and confirm

Configuring Bot Permissions

Under the Bot section, configure these essential settings:

Privileged Gateway Intents:
- MESSAGE CONTENT INTENT: Enabled (required for reading messages)
- SERVER MEMBERS INTENT: Enabled (if tracking member events)
- PRESENCE INTENT: Optional (for user status features)

Generating the Invite URL

Navigate to OAuth2 > URL Generator and select:

Scopes: bot, applications.commands
Bot Permissions: Send Messages, Read Message History, Use Slash Commands, Embed Links, Attach Files

Copy the generated URL and use it to invite your bot to your test server.

Project Setup

Let's initialize our project and install the necessary dependencies.

mkdir neurolink-discord-bot
cd neurolink-discord-bot
npm init -y

Install the required packages:

npm install discord.js @juspay/neurolink dotenv
npm install -D typescript @types/node ts-node nodemon

Initialize TypeScript:

npx tsc --init

Update your tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Project Structure

Organize your project with a clean structure:

neurolink-discord-bot/
├── src/
│   ├── index.ts           # Main entry point
│   ├── config.ts          # Configuration
│   ├── commands/          # Slash commands
│   │   ├── index.ts
│   │   ├── ask.ts
│   │   ├── chat.ts
│   │   └── summarize.ts
│   ├── events/            # Discord event handlers
│   │   ├── ready.ts
│   │   └── interactionCreate.ts
│   ├── services/          # NeuroLink integration
│   │   ├── neurolink.ts
│   │   └── conversation.ts
│   └── utils/             # Helper functions
│       ├── embed.ts
│       └── logger.ts
├── .env
├── package.json
└── tsconfig.json

Environment Configuration

Create a .env file in your project root:

DISCORD_TOKEN=your_discord_bot_token
DISCORD_CLIENT_ID=your_application_client_id
NEUROLINK_API_KEY=your_neurolink_api_key

Create src/config.ts:

import dotenv from 'dotenv';
dotenv.config();

export const config = {
  discord: {
    token: process.env.DISCORD_TOKEN!,
    clientId: process.env.DISCORD_CLIENT_ID!,
  },
  neurolink: {
    apiKey: process.env.NEUROLINK_API_KEY!,
  },
};

// Validate required environment variables
const requiredEnvVars = ['DISCORD_TOKEN', 'DISCORD_CLIENT_ID', 'NEUROLINK_API_KEY'];
for (const envVar of requiredEnvVars) {
  if (!process.env[envVar]) {
    throw new Error(`Missing required environment variable: ${envVar}`);
  }
}

NeuroLink Service Integration

Create the NeuroLink service layer in src/services/neurolink.ts:

import { NeuroLink } from '@juspay/neurolink';
import { config } from '../config';

const neurolink = new NeuroLink();

export interface ChatMessage {
  role: 'user' | 'assistant' | 'system';
  content: string;
}

export interface GenerateOptions {
  systemPrompt?: string;
  maxTokens?: number;
  temperature?: number;
}

export async function generateResponse(
  prompt: string,
  options: GenerateOptions = {}
): Promise<string> {
  const {
    systemPrompt = 'You are a helpful Discord bot assistant. Be concise, friendly, and informative.',
    maxTokens = 1000,
    temperature = 0.7,
  } = options;

  try {
    const result = await neurolink.generate({
      input: { text: prompt },
      systemPrompt,
      provider: 'openai',
      model: 'gpt-4o-mini',
      maxTokens,
      temperature,
    });

    return result?.content ?? 'I could not generate a response.';
  } catch (error) {
    console.error('NeuroLink API error:', error);
    throw new Error('Failed to generate AI response');
  }
}

export async function generateChatResponse(
  messages: ChatMessage[],
  systemPrompt?: string
): Promise<string> {
  // Build conversation text from message history
  const conversationText = messages
    .map((msg) => `${msg.role}: ${msg.content}`)
    .join('\n');

  try {
    const result = await neurolink.generate({
      input: { text: conversationText },
      systemPrompt: systemPrompt || 'You are a helpful assistant.',
      provider: 'openai',
      model: 'gpt-4o-mini',
      maxTokens: 1000,
      temperature: 0.7,
    });

    return result?.content ?? 'I could not generate a response.';
  } catch (error) {
    console.error('NeuroLink API error:', error);
    throw new Error('Failed to generate AI response');
  }
}

export async function summarizeText(text: string): Promise<string> {
  return generateResponse(text, {
    systemPrompt: 'Summarize the following text concisely while preserving key information.',
    maxTokens: 500,
    temperature: 0.3,
  });
}

Conversation Management

For multi-turn conversations, we need to track message history. Create src/services/conversation.ts:

import { ChatMessage } from './neurolink';

interface Conversation {
  messages: ChatMessage[];
  lastActivity: number;
  channelId: string;
  userId: string;
}

class ConversationManager {
  private conversations: Map<string, Conversation> = new Map();
  private readonly maxMessages = 20;
  private readonly timeoutMs = 30 * 60 * 1000; // 30 minutes

  private getKey(userId: string, channelId: string): string {
    return `${userId}-${channelId}`;
  }

  getConversation(userId: string, channelId: string): ChatMessage[] {
    const key = this.getKey(userId, channelId);
    const conversation = this.conversations.get(key);

    if (!conversation) {
      return [];
    }

    // Check if conversation has expired
    if (Date.now() - conversation.lastActivity > this.timeoutMs) {
      this.conversations.delete(key);
      return [];
    }

    return conversation.messages;
  }

  addMessage(userId: string, channelId: string, message: ChatMessage): void {
    const key = this.getKey(userId, channelId);
    let conversation = this.conversations.get(key);

    if (!conversation) {
      conversation = {
        messages: [],
        lastActivity: Date.now(),
        channelId,
        userId,
      };
      this.conversations.set(key, conversation);
    }

    conversation.messages.push(message);
    conversation.lastActivity = Date.now();

    // Trim old messages if exceeding limit
    if (conversation.messages.length > this.maxMessages) {
      conversation.messages = conversation.messages.slice(-this.maxMessages);
    }
  }

  clearConversation(userId: string, channelId: string): void {
    const key = this.getKey(userId, channelId);
    this.conversations.delete(key);
  }

  // Cleanup expired conversations periodically
  cleanup(): void {
    const now = Date.now();
    for (const [key, conversation] of this.conversations.entries()) {
      if (now - conversation.lastActivity > this.timeoutMs) {
        this.conversations.delete(key);
      }
    }
  }
}

export const conversationManager = new ConversationManager();

// Run cleanup every 10 minutes
setInterval(() => conversationManager.cleanup(), 10 * 60 * 1000);

Creating Slash Commands

Command Registration

Create src/commands/index.ts to handle command registration:

import { REST, Routes, SlashCommandBuilder } from 'discord.js';
import { config } from '../config';

export const commands = [
  new SlashCommandBuilder()
    .setName('ask')
    .setDescription('Ask the AI a question')
    .addStringOption((option) =>
      option
        .setName('question')
        .setDescription('Your question for the AI')
        .setRequired(true)
    ),

  new SlashCommandBuilder()
    .setName('chat')
    .setDescription('Have a conversation with the AI')
    .addStringOption((option) =>
      option
        .setName('message')
        .setDescription('Your message to the AI')
        .setRequired(true)
    ),

  new SlashCommandBuilder()
    .setName('summarize')
    .setDescription('Summarize recent channel messages')
    .addIntegerOption((option) =>
      option
        .setName('count')
        .setDescription('Number of messages to summarize (default: 20)')
        .setMinValue(5)
        .setMaxValue(100)
    ),

  new SlashCommandBuilder()
    .setName('clear')
    .setDescription('Clear your conversation history with the AI'),

  new SlashCommandBuilder()
    .setName('help')
    .setDescription('Show available commands and how to use them'),
];

export async function registerCommands(): Promise<void> {
  const rest = new REST().setToken(config.discord.token);

  try {
    console.log('Registering slash commands...');

    await rest.put(Routes.applicationCommands(config.discord.clientId), {
      body: commands.map((cmd) => cmd.toJSON()),
    });

    console.log('Slash commands registered successfully!');
  } catch (error) {
    console.error('Error registering commands:', error);
    throw error;
  }
}

Ask Command

Create src/commands/ask.ts:

import { ChatInputCommandInteraction, EmbedBuilder } from 'discord.js';
import { generateResponse } from '../services/neurolink';

export async function handleAskCommand(
  interaction: ChatInputCommandInteraction
): Promise<void> {
  const question = interaction.options.getString('question', true);

  await interaction.deferReply();

  try {
    const response = await generateResponse(question);

    const embed = new EmbedBuilder()
      .setColor(0x5865f2)
      .setTitle('AI Response')
      .setDescription(response)
      .setFooter({
        text: `Asked by ${interaction.user.username}`,
        iconURL: interaction.user.displayAvatarURL(),
      })
      .setTimestamp();

    await interaction.editReply({ embeds: [embed] });
  } catch (error) {
    console.error('Error in ask command:', error);
    await interaction.editReply({
      content: 'Sorry, I encountered an error while processing your question. Please try again.',
    });
  }
}

Chat Command with Conversation History

Create src/commands/chat.ts:

import { ChatInputCommandInteraction, EmbedBuilder } from 'discord.js';
import { generateChatResponse, ChatMessage } from '../services/neurolink';
import { conversationManager } from '../services/conversation';

const CHAT_SYSTEM_PROMPT = `You are a friendly and helpful Discord bot assistant named NeuroBot.
You can engage in natural conversations, answer questions, help with coding, and provide information.
Keep responses concise but informative. Use markdown formatting when appropriate.
Remember context from previous messages in the conversation.`;

export async function handleChatCommand(
  interaction: ChatInputCommandInteraction
): Promise<void> {
  const message = interaction.options.getString('message', true);
  const userId = interaction.user.id;
  const channelId = interaction.channelId;

  await interaction.deferReply();

  try {
    // Get existing conversation history
    const history = conversationManager.getConversation(userId, channelId);

    // Add user's new message
    const userMessage: ChatMessage = { role: 'user', content: message };
    conversationManager.addMessage(userId, channelId, userMessage);

    // Generate response with full history
    const response = await generateChatResponse(
      [...history, userMessage],
      CHAT_SYSTEM_PROMPT
    );

    // Store assistant's response in history
    conversationManager.addMessage(userId, channelId, {
      role: 'assistant',
      content: response,
    });

    const embed = new EmbedBuilder()
      .setColor(0x57f287)
      .setDescription(response)
      .setFooter({
        text: `Conversation with ${interaction.user.username} | Use /clear to reset`,
        iconURL: interaction.user.displayAvatarURL(),
      });

    await interaction.editReply({ embeds: [embed] });
  } catch (error) {
    console.error('Error in chat command:', error);
    await interaction.editReply({
      content: 'Sorry, I encountered an error. Please try again.',
    });
  }
}

Summarize Command

Create src/commands/summarize.ts:

import {
  ChatInputCommandInteraction,
  EmbedBuilder,
  TextChannel,
  ChannelType,
} from 'discord.js';
import { summarizeText } from '../services/neurolink';

export async function handleSummarizeCommand(
  interaction: ChatInputCommandInteraction
): Promise<void> {
  const count = interaction.options.getInteger('count') || 20;

  if (interaction.channel?.type !== ChannelType.GuildText) {
    await interaction.reply({
      content: 'This command can only be used in text channels.',
      ephemeral: true,
    });
    return;
  }

  await interaction.deferReply();

  try {
    const channel = interaction.channel as TextChannel;
    const messages = await channel.messages.fetch({ limit: count });

    // Filter out bot messages and format for summarization
    const humanMessages = messages
      .filter((msg) => !msg.author.bot && msg.content.length > 0)
      .reverse()
      .map((msg) => `${msg.author.username}: ${msg.content}`)
      .join('\n');

    if (!humanMessages) {
      await interaction.editReply({
        content: 'No messages found to summarize.',
      });
      return;
    }

    const summary = await summarizeText(humanMessages);

    const embed = new EmbedBuilder()
      .setColor(0xfee75c)
      .setTitle(`Summary of Last ${count} Messages`)
      .setDescription(summary)
      .setFooter({
        text: `Requested by ${interaction.user.username}`,
        iconURL: interaction.user.displayAvatarURL(),
      })
      .setTimestamp();

    await interaction.editReply({ embeds: [embed] });
  } catch (error) {
    console.error('Error in summarize command:', error);
    await interaction.editReply({
      content: 'Sorry, I could not summarize the messages. Please try again.',
    });
  }
}

Event Handlers

Ready Event

Create src/events/ready.ts:

import { Client, ActivityType } from 'discord.js';

export function handleReady(client: Client<true>): void {
  console.log(`Bot is online as ${client.user.tag}`);
  console.log(`Serving ${client.guilds.cache.size} server(s)`);

  // Set bot status
  client.user.setPresence({
    activities: [
      {
        name: '/help for commands',
        type: ActivityType.Listening,
      },
    ],
    status: 'online',
  });
}

Interaction Handler

Create src/events/interactionCreate.ts:

import { Interaction, EmbedBuilder } from 'discord.js';
import { handleAskCommand } from '../commands/ask';
import { handleChatCommand } from '../commands/chat';
import { handleSummarizeCommand } from '../commands/summarize';
import { conversationManager } from '../services/conversation';

export async function handleInteraction(interaction: Interaction): Promise<void> {
  if (!interaction.isChatInputCommand()) return;

  const { commandName } = interaction;

  try {
    switch (commandName) {
      case 'ask':
        await handleAskCommand(interaction);
        break;

      case 'chat':
        await handleChatCommand(interaction);
        break;

      case 'summarize':
        await handleSummarizeCommand(interaction);
        break;

      case 'clear':
        conversationManager.clearConversation(
          interaction.user.id,
          interaction.channelId
        );
        await interaction.reply({
          content: 'Your conversation history has been cleared!',
          ephemeral: true,
        });
        break;

      case 'help':
        await handleHelpCommand(interaction);
        break;

      default:
        await interaction.reply({
          content: 'Unknown command.',
          ephemeral: true,
        });
    }
  } catch (error) {
    console.error(`Error handling command ${commandName}:`, error);

    const errorMessage = 'An error occurred while processing your command.';
    if (interaction.deferred || interaction.replied) {
      await interaction.editReply({ content: errorMessage });
    } else {
      await interaction.reply({ content: errorMessage, ephemeral: true });
    }
  }
}

async function handleHelpCommand(interaction: Interaction): Promise<void> {
  if (!interaction.isChatInputCommand()) return;

  const embed = new EmbedBuilder()
    .setColor(0x5865f2)
    .setTitle('NeuroLink Bot Commands')
    .setDescription('Here are all available commands:')
    .addFields(
      {
        name: '/ask <question>',
        value: 'Ask a one-off question to the AI',
      },
      {
        name: '/chat <message>',
        value: 'Have a conversation with the AI (remembers context)',
      },
      {
        name: '/summarize [count]',
        value: 'Summarize recent messages in the channel',
      },
      {
        name: '/clear',
        value: 'Clear your conversation history',
      },
      {
        name: '/help',
        value: 'Show this help message',
      }
    )
    .setFooter({ text: 'Powered by NeuroLink AI' });

  await interaction.reply({ embeds: [embed], ephemeral: true });
}

Main Entry Point

Create src/index.ts:

import { Client, GatewayIntentBits, Partials } from 'discord.js';
import { config } from './config';
import { registerCommands } from './commands';
import { handleReady } from './events/ready';
import { handleInteraction } from './events/interactionCreate';

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent,
    GatewayIntentBits.GuildMembers,
  ],
  partials: [Partials.Message, Partials.Channel],
});

// Event handlers
client.once('ready', (c) => handleReady(c));
client.on('interactionCreate', handleInteraction);

// Error handling
client.on('error', (error) => {
  console.error('Discord client error:', error);
});

process.on('unhandledRejection', (error) => {
  console.error('Unhandled promise rejection:', error);
});

// Start the bot
async function main(): Promise<void> {
  try {
    await registerCommands();
    await client.login(config.discord.token);
  } catch (error) {
    console.error('Failed to start bot:', error);
    process.exit(1);
  }
}

main();

Adding Advanced Features

Rate Limiting

Protect your API usage with rate limiting. Create src/utils/rateLimiter.ts:

interface RateLimitEntry {
  count: number;
  resetTime: number;
}

class RateLimiter {
  private limits: Map<string, RateLimitEntry> = new Map();
  private readonly maxRequests: number;
  private readonly windowMs: number;

  constructor(maxRequests = 10, windowMs = 60000) {
    this.maxRequests = maxRequests;
    this.windowMs = windowMs;
  }

  isRateLimited(userId: string): boolean {
    const now = Date.now();
    const entry = this.limits.get(userId);

    if (!entry || now > entry.resetTime) {
      this.limits.set(userId, {
        count: 1,
        resetTime: now + this.windowMs,
      });
      return false;
    }

    if (entry.count >= this.maxRequests) {
      return true;
    }

    entry.count++;
    return false;
  }

  getRemainingTime(userId: string): number {
    const entry = this.limits.get(userId);
    if (!entry) return 0;
    return Math.max(0, entry.resetTime - Date.now());
  }
}

export const rateLimiter = new RateLimiter(10, 60000); // 10 requests per minute

Streaming Responses

For long responses, implement streaming updates:

import { ChatInputCommandInteraction, EmbedBuilder } from 'discord.js';
import { NeuroLink } from '@juspay/neurolink';

export async function handleStreamingResponse(
  interaction: ChatInputCommandInteraction,
  prompt: string
): Promise<void> {
  await interaction.deferReply();

  const neurolink = new NeuroLink();

  let fullResponse = '';
  let lastUpdate = Date.now();
  const updateInterval = 1500; // Update every 1.5 seconds

  const result = await neurolink.stream({
    input: { text: prompt },
    systemPrompt: 'You are a helpful Discord bot assistant.',
    provider: 'openai',
    model: 'gpt-4o',
  });

  for await (const chunk of result.stream) {
    if ('content' in chunk) {
      fullResponse += chunk.content;
    }

    // Update message periodically to avoid rate limits
    if (Date.now() - lastUpdate > updateInterval) {
      const embed = new EmbedBuilder()
        .setDescription(fullResponse + ' ...')
        .setColor(0x5865f2);

      await interaction.editReply({ embeds: [embed] });
      lastUpdate = Date.now();
    }
  }

  // Final update
  const finalEmbed = new EmbedBuilder()
    .setDescription(fullResponse)
    .setColor(0x57f287)
    .setFooter({ text: 'Response complete' });

  await interaction.editReply({ embeds: [finalEmbed] });
}

Message-Based Triggers

Add automatic responses to @mentions:

// Add to src/index.ts
client.on('messageCreate', async (message) => {
  // Ignore bots and messages without mentions
  if (message.author.bot) return;
  if (!message.mentions.has(client.user!)) return;

  // Remove the mention from the message
  const content = message.content
    .replace(/<@!?\d+>/g, '')
    .trim();

  if (!content) {
    await message.reply('How can I help you? Ask me anything!');
    return;
  }

  try {
    await message.channel.sendTyping();

    const response = await generateResponse(content, {
      systemPrompt: 'You are a helpful Discord bot. Keep responses brief and friendly.',
      maxTokens: 500,
    });

    await message.reply(response);
  } catch (error) {
    console.error('Error responding to mention:', error);
    await message.reply('Sorry, I encountered an error. Please try again.');
  }
});

Deployment

Package Scripts

Update package.json:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "nodemon --exec ts-node src/index.ts",
    "register": "ts-node src/commands/index.ts"
  }
}

Docker Deployment

Create a Dockerfile:

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY dist/ ./dist/

ENV NODE_ENV=production

CMD ["node", "dist/index.js"]

Create docker-compose.yml:

version: '3.8'
services:
  bot:
    build: .
    restart: unless-stopped
    env_file:
      - .env
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Cloud Deployment Options

Railway:

railway login
railway init
railway up

Fly.io:

fly launch
fly secrets set DISCORD_TOKEN=xxx NEUROLINK_API_KEY=xxx
fly deploy

DigitalOcean App Platform:

Connect your GitHub repository
Set environment variables in the dashboard
Deploy with automatic scaling

Best Practices

Error Handling

Always wrap API calls in try-catch blocks and provide user-friendly error messages:

try {
  const response = await generateResponse(prompt);
  await interaction.editReply({ content: response });
} catch (error) {
  if (error.code === 'RATE_LIMITED') {
    await interaction.editReply({
      content: 'I\'m receiving too many requests. Please wait a moment.',
    });
  } else {
    await interaction.editReply({
      content: 'Something went wrong. Please try again later.',
    });
  }
  console.error('API Error:', error);
}

Security Considerations

Never expose API keys - Use environment variables
Validate user input - Sanitize before sending to APIs
Implement rate limiting - Prevent abuse
Use ephemeral messages - For sensitive responses
Log responsibly - Don't log user messages in production

Performance Optimization

Cache frequently used data - Reduce API calls
Use connection pooling - For database connections
Implement request queuing - Handle traffic spikes
Monitor response times - Set up alerting
Request cancellation - Use AbortController for timeout handling

Note: Timeout-based cancellation is available via the timeout parameter in NeuroLink.

Testing Your Bot

Create a simple test script:

// src/test.ts
import { generateResponse } from './services/neurolink';

async function test() {
  console.log('Testing NeuroLink integration...');

  const response = await generateResponse('What is Discord?');
  console.log('Response:', response);

  console.log('Test completed successfully!');
}

test().catch(console.error);

Run with: npx ts-node src/test.ts

What You Built

You built an AI Discord bot with slash commands, multi-turn conversations, thread summarization, and mention responses using Discord.js and NeuroLink's generation API. The bot handles natural language queries, maintains conversation context per thread, and provides AI-powered moderation and analysis.

Continue with these related tutorials:

Building a Slack Bot with AI for similar patterns on a different platform
MCP Server Tutorial for exposing your bot's capabilities as reusable AI tools
Speech-to-Text with NeuroLink for adding voice capabilities to voice channels

Resources

Have questions about building Discord bots with NeuroLink? Join our Discord community or reach out on Twitter.

Related posts:

Four MCP transports: stdio, http, sse, websocket — picking the right one

NeuroLink AI — Sat, 04 Jul 2026 04:02:01 +0000

We built the first NeuroLink MCP server manager to run external tools as subprocesses, communicating over stdio. It was simple, self-contained, and it worked perfectly for tools that were packaged with the main application. Then we deployed a new tool at Juspay, a Python-based document analyzer running in its own Docker container. The stdio transport failed instantly. The parent NeuroLink process couldn't spawn a process inside a separate container, and even if it could, we had no way to monitor the tool's health, manage its lifecycle, or scale it independently. That failure forced us to decouple the tool from the agent, leading to the four-transport architecture MCP uses today: stdio for simple cases, and HTTP, Server-Sent Events (SSE), and WebSockets for robust, networked tool execution.

The Problem with Tight Coupling

The original MCP transport, stdio, treats a tool like a command-line utility. When you register a server with this transport, the ExternalServerManager spawns the tool's process and attaches to its stdin, stdout, and stderr streams.

This is a valid approach for simple, co-located tools. For example, a small Node.js script that lives on the same machine as the NeuroLink agent.

// Example: a local stdio server (type MCPServerInfo)

const localScriptServer: MCPServerInfo = {
  id: 'local-script-server',
  name: 'Local Script Server',
  transport: 'stdio',
  command: 'node',
  args: ['./tools/my-local-script.js', '--mcp'],
  // ... status, tools, and other fields
};

The problem is that this creates a rigid parent-child relationship.

Lifecycle Coupling: If the NeuroLink agent restarts, the tool process is killed. If the tool process crashes, the agent might not have a clean way to restart it or understand why it failed. This is a classic cascading failure scenario we try to avoid, as discussed in our post on the MCP Circuit Breaker pattern. The ExternalServerManager, located in src/lib/mcp/externalServerManager.ts, has to contain complex logic just to handle unexpected process exits and prevent zombie processes, which is a significant overhead for what should be a simple transport.
No Network Visibility: The tool isn't on the network. You can't hit it with curl, you can't put a load balancer in front of it, and you can't easily run it in a separate container managed by Kubernetes or another orchestrator. This also means you can't have multiple agents share a single instance of a resource-intensive tool.
Debugging Hell: When something goes wrong, you're limited to parsing text from stderr. There's no structured error format, no HTTP status codes, and no easy way to inspect the state of the tool server. Is the tool hanging, or is it just slow? Is it consuming too much memory? With stdio, you're flying blind. This puts an enormous burden on developers to write tools that are perfectly behaved and produce easily parsable error messages.

HTTP: Stateless, Scalable, and Standard

To solve the containerization problem we saw at Juspay, we introduced the HTTP transport. An MCP server using the http transport is just a standard web server that exposes a specific endpoint for tool calls.

NeuroLink's ExternalServerManager doesn't spawn this process. It simply needs to know the URL.

// Example: a remote HTTP server (type MCPServerInfo)

const remoteHttpServer: MCPServerInfo = {
  id: 'document-analyzer-prod',
  name: 'Production Document Analyzer',
  transport: 'http',
  url: 'https://tools.juspay.in/document-analyzer',
  // headers / auth are top-level fields (see below)
};

This immediately solves the problems with stdio:

Decoupled Lifecycle: The tool server is a completely independent service. It can be deployed, scaled, and updated without affecting the NeuroLink agent that calls it.
Network Native: It's on the network. This means you can use standard infrastructure for load balancing, health checks, and security.
Observability: Every tool call is an HTTP request. This makes it trivial to integrate with standard monitoring and tracing tools. You can see every request, its latency, and its status code, which is critical for maintaining quality. Our entire philosophy around OpenTelemetry for AI relies on this kind of visibility.

The tradeoff is the stateless nature of HTTP. Every executeTool call is a new, independent request. For tools that require a continuous, stateful conversation, the overhead of establishing a new HTTP connection for every message can be inefficient.

Authentication Across Transports

Moving from a trusted, local stdio process to a networked HTTP or WebSocket server introduces a critical new problem: security. A tool server exposed on the network is a potential vulnerability. It needs to know who is calling it and whether they are authorized.

The stdio transport has no concept of authentication; the trust is implicit because the agent process is the parent of the tool process. For networked transports, we explicitly provide configuration for this in MCPServerInfo.

The top-level headers field on the server config is the key. It lets you specify headers sent with every request — most commonly an API key or a bearer token. (A dedicated auth field handles the common token cases for you.)

// Example: an authenticated HTTP server (type MCPServerInfo)

const secureHttpServer: MCPServerInfo = {
  id: 'secure-internal-tool',
  name: 'Secure Internal Tool',
  transport: 'http',
  url: 'https://tools.internal/secure-tool/execute',
  headers: {
    'Authorization': 'Bearer super-secret-token-from-env',
    'X-Request-Source': 'neurolink-mcp'
  },
  // or use the dedicated auth field: auth: { type: 'bearer', token: '...' }
};

For WebSockets, authentication is handled similarly during the initial HTTP Upgrade request. The same headers can be passed to verify the client's identity before the protocol switch occurs. This ensures that only trusted NeuroLink agents can connect to and execute your tools, preventing unauthorized access.

SSE and WebSockets: For Streaming and Conversations

While HTTP is the workhorse for most tool calls, some tools need a more persistent connection.

Server-Sent Events (SSE): For when a tool needs to stream updates to the agent. Think of a long-running task like code generation or a data analysis job. The tool can push progress events, logs, or partial results over a single, long-lived connection. The agent listens, but it can't easily talk back. This is a one-way firehose of data from the tool to the agent.
WebSockets: For when you need a true two-way conversation. The connection is persistent and full-duplex. This is ideal for highly interactive tools, like a "clarification agent" that asks follow-up questions before executing a task — the kind of elicitation the ElicitationProtocolHandler coordinates (it works over any transport, not just WebSockets). In this model, the executeTool can maintain context across multiple message exchanges, which is impossible with stateless HTTP and cumbersome with stdio.

The configuration in MCPServerInfo remains simple. You just declare the transport type and the endpoint.

// Example: SSE and WebSocket servers (type MCPServerInfo)

const streamingReportServer: MCPServerInfo = {
  id: 'streaming-reporter',
  name: 'Streaming Reporter',
  transport: 'sse',
  url: 'https://tools.juspay.in/reports/stream',
};

const conversationalAgentServer: MCPServerInfo = {
  id: 'clarification-agent',
  name: 'Clarification Agent',
  transport: 'websocket',
  url: 'wss://tools.juspay.in/clarify-agent',
};

The Factory Pattern: Unifying Transport Clients

With four different transport types, how does the ExternalServerManager avoid becoming a tangled mess of conditional logic? The answer is a classic software design pattern: the factory.

Inside src/lib/mcp/mcpClientFactory.ts, we keep a MCPClientFactory class that exposes a static createClient method. The ExternalServerManager does not know how to speak HTTP, open a WebSocket, or manage stdio pipes. It performs a single action: it hands an MCPServerInfo to the factory, and gets back a connected client with the matching transport already wired up.

// src/lib/mcp/mcpClientFactory.ts (shape)

export class MCPClientFactory {
  static async createClient(
    config: MCPServerInfo,
    timeout = DEFAULT_CLIENT_TIMEOUT,
  ): Promise<MCPClientResult> {
    // dispatch on config.transport (a plain string):
    //   "stdio"     → spawn a child process, wire stdin/stdout
    //   "http"      → open an HTTP client against config.url
    //   "sse"       → attach an SSE listener for server → client streaming
    //   "websocket" → open a full-duplex WebSocket
    // returns: { client, capabilities, transport } on success
    //          { error } on failure (no exception thrown into the caller)
  }
}

The factory returns an object that conforms to a common interface, abstracting away the connection details. Adding a new transport in the future — gRPC, QUIC, or something proprietary — does not require touching the ExternalServerManager. The new transport class slots into the same dispatch and the rest of the system keeps working unchanged.

Common Failure Modes

Decoupling introduces new failure modes, most of which are network-related. The ExternalServerManager, by consuming clients from MCPClientFactory.createClient, is also responsible for handling their distinct failures.

stdio Failures: The most common issues are process-related. The command in MCPServerInfo might point to a non-existent binary (ENOENT), or the file might not have execute permissions (EACCES). If the process starts but then immediately exits with a non-zero status code, ExternalServerManager in src/lib/mcp/externalServerManager.ts must capture stderr to provide a meaningful error message.
http Failures: These are standard network errors. The DNS name for the endpoint might not resolve. The server might be down, refusing the connection. It could return a 503 Service Unavailable, indicating a temporary overload, which might warrant a retry. Or it could return a 401 Unauthorized, indicating a problem with the auth token. The client must interpret these HTTP status codes correctly.
sse / websocket Failures: These stateful connections can fail at any time. A network hiccup can sever the connection mid-stream. The WebSocketClient needs a robust reconnection strategy, likely with exponential backoff, to avoid overwhelming a recovering server. It also needs to handle the case where a message is sent while the connection is down. Does it queue the message, or does it fail the executeTool call immediately? The answer depends on the tool's requirements for guaranteed delivery.

Here's a visual breakdown of how these transports relate the NeuroLink agent to the tool server:

graph TD
    subgraph NeuroLink Agent
        A[ExternalServerManager]
    end

    subgraph "Transport Layer"
        T_STDIO[stdio]
        T_HTTP[http]
        T_SSE[sse]
        T_WS[websocket]
    end

    subgraph Tool Servers
        S_STDIO(Tool as Child Process)
        S_HTTP(Tool as HTTP Server)
        S_SSE(Tool as SSE Server)
        S_WS(Tool as WebSocket Server)
    end

    A -- "spawn(), pipe" --> T_STDIO -- "stdin/stdout" --> S_STDIO
    A -- "POST /execute" --> T_HTTP --- S_HTTP
    A -- "GET /stream" --> T_SSE -- "event-stream" --> A
    A -- "Upgrade: websocket" <--> T_WS <--> S_WS

Configuration at a Glance

Every server is declared the same way — an MCPServerInfo carrying a transport string plus the fields that transport needs (command for stdio, url for the network transports). The trade-offs each one carries are what should drive the choice:

Transport	`transport` value	Direction	Connection	Best for	Primary failure mode
stdio	`'stdio'`	bidirectional pipe	per-process, local	local scripts bundled with the agent	`ENOENT` / `EACCES` / non-zero exit
HTTP	`'http'`	request / response	stateless	remote, single-call tools	DNS failure, 503, 401
SSE	`'sse'`	server → client	long-lived, one-way	streaming progress and partial results	mid-stream disconnect
WebSocket	`'websocket'`	full-duplex	persistent	conversational, multi-turn tools	disconnect needing backoff reconnect

The MCPClientFactory reads that single transport string and hands back a ready client, so moving a tool from http to websocket is a one-line config change — the ExternalServerManager and your executeTool calls stay exactly the same.

Picking the Right Transport

There's no single "best" transport; the right choice depends entirely on the tool's architecture and how it needs to communicate.

stdio: Use this for simple, local scripts that are packaged directly with your agent. It's great for development or for tools you control completely in a monolithic environment. The lack of network configuration makes it the fastest way to get started. It's often sufficient for the kinds of validation scripts you might run in a CI pipeline, like those described in our post on GitHub Actions for AI.
http: This is your default for any tool that runs as a separate service. It's robust, scalable, and easy to manage with standard cloud infrastructure. If your tool can perform its function in a single, stateless call, HTTP is the right choice. Its ubiquity means you have a vast ecosystem of proxies, load balancers, and monitoring tools at your disposal.
sse: Choose SSE when your tool performs a long-running, read-only operation and you want to provide progress updates to the user or agent. It's a one-way street from the server to the client. This is perfect for streaming back log messages, status updates, or chunks of a large response as they become available.
websocket: Reserve WebSockets for tools that are truly conversational. If the tool needs to ask questions, get clarifications, or have a low-latency, back-and-forth exchange with the agent, the full-duplex nature of WebSockets is what you need. This is the most powerful but also the most complex transport to manage.

By supporting all four, NeuroLink's MCP allows you to executeTool against any kind of tool, from a local script to a globally distributed service, without changing your application-level code. You just point the ExternalServerManager at a new MCPServerInfo, and it handles the rest.

Related posts:

Tracing Tool Calls in MCP Workflows: Per-Tool Latency, Cost, and Failure Modes

NeuroLink AI — Sat, 16 May 2026 06:40:13 +0000

Tracing Tool Calls in MCP Workflows: Per-Tool Latency, Cost, and Failure Modes

MCP agents are opaque by default. You call generate(), the model decides to invoke four tools, and three seconds later you get an answer. Which tool took 2.8 of those seconds? Was it the database lookup? The file read? The search API that's been flaky since Tuesday?

Without per-tool tracing, you're debugging a black box.

This article builds on three earlier pieces — AI Observability: Logging, Tracing, and Monitoring Your AI Calls, Building AI Agents with MCP and TypeScript in 2026, and OpenTelemetry for AI: Tracing Every Token Through Your Pipeline — and goes one level deeper: tracing individual tool invocations in multi-step MCP workflows, not just the outer LLM call.

Why Tool-Level Tracing Matters

A typical MCP workflow looks like this:

User prompt
  → search (github.search_code)         ~200ms
  → read × 3 (github.read_file)         ~150ms × 3
  → analyze (code-analyzer.check)       ~2,800ms  ← the real bottleneck
  → write (github.create_issue)         ~300ms
Total: ~3,750ms

If you only trace the outer generate() call, you see 3.75 seconds and conclude "the LLM is slow." It isn't. The analyzer tool is slow, and it's probably doing something fixable — a missing index, a cold lambda, an API without keepalive.

A "slow agent" is almost always one slow tool. The rest is noise.

The Tracing Architecture

The pattern has three parts:

NeuroLink's transformParams hook — fires before each tool invocation, starts an OTEL span
NeuroLink's transformResponse hook — fires after each tool returns, ends the span with latency + outcome
onError hook — fires on tool failures, records the error type and whether it's retryable

You wrap the MCP tool layer with spans, not the entire generate() call. This gives you one span per tool call, nested under the parent trace.

Setup: OpenTelemetry + NeuroLink

npm install @juspay/neurolink
npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-otlp-http

Initialize your tracer once at startup:

// tracing.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-otlp-http";
import { trace, SpanStatusCode } from "@opentelemetry/api";

export const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? "http://localhost:4318/v1/traces",
  }),
});

sdk.start();

export const tracer = trace.getTracer("neurolink-mcp-agent", "1.0.0");
export { SpanStatusCode };

Wrapping Each Tool Call in a Span

NeuroLink's middleware system exposes transformParams and transformResponse. For MCP tool tracing, you write middleware that instruments the tool dispatch layer.

Here's the core pattern:

import { NeuroLink } from "@juspay/neurolink";
import { tracer, SpanStatusCode } from "./tracing";
import { context, trace } from "@opentelemetry/api";

// Track in-flight spans by tool call ID so we can close them on response
const activeSpans = new Map<string, ReturnType<typeof tracer.startSpan>>();

const mcpTracingMiddleware = {
  name: "mcp-tool-tracer",
  priority: 115, // Runs before analytics, after transform

  transformParams: async (params: any, ctx: any) => {
    // Only instrument MCP tool calls, not direct generate() calls
    if (!params.toolCall) return params;

    const toolName = params.toolCall.name;
    const serverId = params.toolCall.serverId ?? "unknown";
    const callId = params.toolCall.id ?? `${toolName}-${Date.now()}`;

    // Start a span as a child of the current active trace
    const parentContext = ctx.traceContext ?? context.active();
    const span = tracer.startSpan(
      `mcp.tool.${toolName}`,
      {
        attributes: {
          "mcp.tool.name": toolName,
          "mcp.server.id": serverId,
          "mcp.call.id": callId,
          "mcp.input.size": JSON.stringify(params.toolCall.input ?? {}).length,
        },
      },
      parentContext
    );

    activeSpans.set(callId, span);

    // Attach call start time for latency calculation
    return { ...params, _spanCallId: callId, _spanStartMs: Date.now() };
  },

  transformResponse: async (response: any, params: any) => {
    const callId = params._spanCallId;
    if (!callId) return response;

    const span = activeSpans.get(callId);
    if (!span) return response;

    const latencyMs = Date.now() - (params._spanStartMs ?? Date.now());

    span.setAttributes({
      "mcp.latency_ms": latencyMs,
      "mcp.output.size": JSON.stringify(response?.result ?? {}).length,
      "mcp.success": true,
    });
    span.setStatus({ code: SpanStatusCode.OK });
    span.end();
    activeSpans.delete(callId);

    return response;
  },
};

Handling Failure Modes

MCP tool failures come in three distinct flavors, and they need different handling:

const mcpErrorMiddleware = {
  name: "mcp-error-classifier",
  onError: (error: Error, metadata: any) => {
    const callId = metadata._spanCallId;
    const span = callId ? activeSpans.get(callId) : undefined;

    // Classify the failure
    let errorClass: string;
    let retryable: boolean;

    if (error.message.includes("ETIMEDOUT") || error.message.includes("timeout")) {
      // Tool server didn't respond in time
      errorClass = "timeout";
      retryable = true;
    } else if (error.message.includes("rate_limit") || error.message.includes("429")) {
      // Tool's upstream API is rate-limited
      errorClass = "rate_limit";
      retryable = true; // After backoff
    } else if (
      error.message.includes("SyntaxError") ||
      error.message.includes("JSON") ||
      error.message.includes("schema")
    ) {
      // Tool returned malformed output
      // This is almost always a tool implementation bug, not a transient error
      errorClass = "malformed_output";
      retryable = false;
    } else {
      errorClass = "unknown";
      retryable = metadata.recoverable ?? false;
    }

    if (span) {
      span.setAttributes({
        "mcp.error.class": errorClass,
        "mcp.error.message": error.message,
        "mcp.error.retryable": retryable,
        "mcp.latency_ms": Date.now() - (metadata._spanStartMs ?? Date.now()),
      });
      span.setStatus({
        code: SpanStatusCode.ERROR,
        message: `${errorClass}: ${error.message}`,
      });
      span.end();

      if (callId) activeSpans.delete(callId);
    }

    // Don't swallow — NeuroLink re-throws after onError fires
    logger.error("mcp_tool_error", {
      tool: metadata.toolCall?.name,
      errorClass,
      retryable,
      message: error.message,
    });
  },
};

The malformed output case deserves special attention. When a tool returns JSON that doesn't match the schema the LLM expected, the model may retry the tool call silently — or hallucinate an answer without the data. Both are bad. Tag these errors distinctly so you can find them in your trace backend.

Trace ID Propagation Across the Agent Run

Each generate() call should share a single trace ID so you can reconstruct the full tool chain in your trace viewer. Pass the trace context explicitly:

import { NeuroLink } from "@juspay/neurolink";
import { tracer, SpanStatusCode } from "./tracing";
import { context, propagation, ROOT_CONTEXT } from "@opentelemetry/api";

async function runAgent(prompt: string, agentRunId: string) {
  // Create the root span for the entire agent run
  const rootSpan = tracer.startSpan("agent.run", {
    attributes: {
      "agent.run_id": agentRunId,
      "agent.prompt_length": prompt.length,
    },
  });

  // All tool spans created during this generate() will be children of rootSpan
  const agentContext = trace.setSpan(context.active(), rootSpan);

  const ai = new NeuroLink({
    provider: "anthropic",
    model: "claude-sonnet-4-6",
    apiKey: process.env.ANTHROPIC_API_KEY,
    middleware: [mcpTracingMiddleware, mcpErrorMiddleware],
  });

  await ai.addExternalMCPServer("github", {
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-github"],
    transport: "stdio",
    env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
  });

  let result: any;

  await context.with(agentContext, async () => {
    result = await ai.generate({
      input: { text: prompt },
    });
  });

  rootSpan.setAttributes({
    "agent.tool_calls": result?.toolCalls?.length ?? 0,
    "agent.tokens.total": result?.usage?.totalTokens ?? 0,
    "agent.success": true,
  });
  rootSpan.setStatus({ code: SpanStatusCode.OK });
  rootSpan.end();

  return result;
}

In Jaeger, Grafana Tempo, or Honeycomb, this renders as a flame graph: the root span contains the LLM call, the LLM call contains all the tool spans, each tool span shows latency and outcome. The slow tool stands out immediately.

What to Track Per Tool

Once you have spans, you want these attributes on every tool call:

Attribute	Why
`mcp.tool.name`	Which tool — the primary grouping key
`mcp.server.id`	Which MCP server — helps distinguish tools with the same name on different servers
`mcp.latency_ms`	The single most useful number for debugging slow agents
`mcp.input.size`	Large inputs often cause timeouts; correlate with latency
`mcp.output.size`	Unexpected output sizes suggest a schema mismatch
`mcp.error.class`	`timeout` / `rate_limit` / `malformed_output` — drives alerting strategy
`mcp.error.retryable`	Whether the agent should attempt this tool call again

For cost-bearing tools (ones that hit paid APIs internally), you can add mcp.estimated_cost_usd from your internal pricing table. The tool cost is often larger than the LLM cost for data-heavy workflows.

A note on where this data lives: NeuroLink's generate() result exposes a toolCalls array (each entry is {toolCallId, toolName, args}) plus toolExecutions ({name, input, output}) and toolResults. The middleware sees the full call/response inside transformParams / wrapGenerate — that's where you do the rich span work — but the post-generation summary is also available on the result object for ad-hoc analytics.

Per-Tool Latency Budgets

You can extend the tracing middleware to enforce latency budgets per tool class — failing fast instead of waiting for a timeout:

const TOOL_TIMEOUT_MS: Record<string, number> = {
  "github.read_file": 5_000,
  "github.search_code": 8_000,
  "database.query": 3_000,
  "web.search": 10_000,
};

const timeoutMiddleware = {
  name: "tool-timeout",
  priority: 125,
  transformParams: async (params: any) => {
    if (!params.toolCall) return params;

    const toolName = params.toolCall.name;
    const budget = TOOL_TIMEOUT_MS[toolName];

    if (budget) {
      // Attach deadline for downstream middleware/provider to enforce
      return { ...params, toolCall: { ...params.toolCall, timeoutMs: budget } };
    }
    return params;
  },
};

A practical note on timeoutMs: NeuroLink's tool registration accepts a per-tool timeoutMs (see ToolRegistrationOptions in the SDK) and forwards it to the tool executor for MCP-level enforcement — so registering a tool with { execute, timeoutMs: 3000 } is the cleanest way to set a hard per-tool deadline. The middleware pattern above mutates params.toolCall.timeoutMs, which is only useful if you have a downstream middleware that reads it — pick one approach, not both.

Putting It All Together

import { NeuroLink } from "@juspay/neurolink";

const ai = new NeuroLink({
  provider: "anthropic",
  model: "claude-sonnet-4-6",
  apiKey: process.env.ANTHROPIC_API_KEY,
  middleware: [
    timeoutMiddleware,      // Priority 125: set per-tool deadlines
    mcpTracingMiddleware,   // Priority 115: open/close OTEL spans
    mcpErrorMiddleware,     // Priority 115: classify errors (onError hook)
    // Priority 100: NeuroLink's built-in analytics middleware
  ],
});

await ai.addExternalMCPServer("github", {
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-github"],
  transport: "stdio",
  env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
});

// Run with trace propagation
const result = await runAgent(
  "Find all files using processPayment() and create a security issue if any lack input validation",
  "run-" + crypto.randomUUID()
);

Your trace now shows:

Root span: total agent execution time
LLM span: actual model inference time (usually the smallest component)
Tool spans: github.search_code, github.read_file × N, github.create_issue with individual latencies
Error spans: any tools that failed, with error class and retryable flag

The model is usually not your bottleneck. The tools are. Now you can prove it.

Get started with NeuroLink:

GitHub: https://github.com/juspay/neurolink
npm: npm install @juspay/neurolink
Docs: https://blog.neurolink.ink/docs
Blog: https://blog.neurolink.ink

Productionizing Ollama: Rate Limits, Cloud Fallback, and Cost Guardrails

NeuroLink AI — Sat, 16 May 2026 02:39:44 +0000

Productionizing Ollama: Rate Limits, Cloud Fallback, and Cost Guardrails

Running Ollama locally is easy. Running it in a production service that handles concurrent users without melting your box — that's a different problem.

I wrote up the basic Ollama + NeuroLink setup in Running Local LLMs with NeuroLink and Ollama: Complete Guide. This article is the follow-up: what happens after you ship it and it gets real traffic.

Three things break first: request queues pile up under concurrency, latency spikes on heavier models, and you have no budget guardrails because "it's free" turns out not to mean "it can't cause you problems." Here's how to solve all three.

The Problem: Ollama Has No Native Rate Limiting

OpenAI returns a 429 when you hit its rate limit. Ollama doesn't have a rate limit — it queues requests and processes them serially on whatever GPU you have. Five concurrent requests to llama3.1:70b on a single machine means the fifth request waits for the first four to finish.

In practice, your p99 latency goes from 4 seconds to 20 seconds and your users give up.

You need to impose your own rate limiting at the SDK layer before requests reach the Ollama process.

Pattern 1: Request Throttling via Middleware

NeuroLink's middleware system runs as a pipeline on every generate() call. A throttling middleware can reject or queue requests before they're dispatched to the provider:

import { NeuroLink } from "@juspay/neurolink";

// Simple token-bucket rate limiter
class TokenBucket {
  private tokens: number;
  private lastRefill = Date.now();

  constructor(
    private readonly capacity: number,
    private readonly refillRatePerSecond: number
  ) {
    this.tokens = capacity;
  }

  consume(): boolean {
    const now = Date.now();
    const elapsed = (now - this.lastRefill) / 1000;
    this.tokens = Math.min(
      this.capacity,
      this.tokens + elapsed * this.refillRatePerSecond
    );
    this.lastRefill = now;

    if (this.tokens >= 1) {
      this.tokens -= 1;
      return true;
    }
    return false;
  }
}

const bucket = new TokenBucket(10, 2); // 10 burst, 2 req/sec sustained

const throttleMiddleware = {
  name: "ollama-throttle",
  priority: 120, // Runs before everything else
  transformParams: async (params: any) => {
    if (!bucket.consume()) {
      throw new Error("LOCAL_RATE_LIMIT: Ollama request queue full");
    }
    return params;
  },
};

const ai = new NeuroLink({
  provider: "ollama",
  model: "llama3.1",
  middleware: [throttleMiddleware],
});

The middleware throws a LOCAL_RATE_LIMIT error before the request reaches Ollama. Your calling code catches this and routes elsewhere — which brings us to the next pattern.

Pattern 2: Falling Back to Cloud When Local is Overloaded

This is the multi-provider fallback pattern from Building Resilient AI: Multi-Provider Fallback Patterns in TypeScript applied specifically to the Ollama overload scenario.

NeuroLink's fallbackChain handles provider-level failures automatically, but the throttle middleware above throws before the provider is even called. You need to catch that specific error and escalate.

Here's the full pattern:

import { NeuroLink } from "@juspay/neurolink";

// Primary: local Ollama with throttle
const localAI = new NeuroLink({
  provider: "ollama",
  model: "llama3.1",
  middleware: [throttleMiddleware],
});

// Fallback: cloud providers in priority order
const cloudAI = new NeuroLink({
  providers: [
    { name: "anthropic", model: "claude-3-5-haiku-20241022", priority: 1 },
    { name: "openai", model: "gpt-4o-mini", priority: 2 },
  ],
  fallbackChain: ["anthropic", "openai"],
});

async function generate(prompt: string) {
  try {
    return await localAI.generate({ input: { text: prompt } });
  } catch (err: any) {
    if (err.message?.startsWith("LOCAL_RATE_LIMIT")) {
      // Ollama queue full — route to cloud
      console.warn("Ollama saturated, routing to cloud");
      return await cloudAI.generate({ input: { text: prompt } });
    }
    throw err; // Re-throw unexpected errors
  }
}

const result = await generate("Summarize this support ticket...");
console.log(`Provider used: ${result.provider}`);

The critical thing here: you want Haiku or GPT-4o-mini as your cloud fallback, not Claude Sonnet or GPT-4o. The fallback scenario is "Ollama is busy" — you're handling overflow, not upgrading quality. Match the capability tier, not the price tier.

Pattern 3: Latency Budgets — Switching on Timeout

Queue saturation isn't the only signal that Ollama is struggling. A 70B model under thermal throttling might accept the request but take 30 seconds to answer. You need a latency budget.

NeuroLink's generate() accepts a timeout option (number ms or string like "8s") plus an abortSignal, and the FallbackConfig chain triggers on errors — including timeout errors. Combine both for a clean latency-budget pattern:

import { NeuroLink } from "@juspay/neurolink";

const ai = new NeuroLink({
  providers: [
    {
      name: "ollama",
      model: "llama3.1",
      priority: 1,
    },
    {
      name: "anthropic",
      model: "claude-3-5-haiku-20241022",
      priority: 2,
      apiKey: process.env.ANTHROPIC_API_KEY,
    },
  ],
  fallbackConfig: {
    enabled: true,
    maxAttempts: 2, // ollama, then anthropic
    circuitBreaker: true,
  },
});

const result = await ai.generate({
  input: { text: prompt },
  timeout: 8000, // 8s budget for the call; throws → fallback chain takes over
});

// Log which provider actually served this request
if (result.provider !== "ollama") {
  console.warn(`Latency budget exceeded, fell back to ${result.provider}`);
  metrics.increment("ollama.latency_fallback");
}

Set your timeout conservatively. An 8-second budget for an interactive request is already too slow for chat. If you're building a real-time interface, consider 3-4 seconds and accepting that heavy models will frequently fall back. Batch processing can afford 15-30 seconds.

The timeout option applies to the whole generate() call. For a strict per-provider deadline (e.g., "give Ollama exactly 3 seconds before racing Claude"), wrap each provider's call in a Promise.race with your own AbortController — the SDK doesn't expose a per-provider timeout field directly.

Pattern 4: Cost Guardrails with the onFinish Hook

"Ollama is free" is true for the LLM calls themselves. It's not true for:

Cloud fallback calls (every Anthropic/OpenAI request costs money)
Your compute bill if you're running Ollama on cloud GPU instances
The engineering time debugging a service that's silently spending money

The onFinish lifecycle hook fires after every successful generation with usage data and provider info. Use it to track where your spend is going:

import { NeuroLink } from "@juspay/neurolink";

// Per-1K token pricing (cloud fallback providers)
const CLOUD_PRICING: Record<string, { input: number; output: number }> = {
  "claude-3-5-haiku-20241022": { input: 0.0008, output: 0.004 },
  "gpt-4o-mini": { input: 0.00015, output: 0.0006 },
};

let sessionCost = 0;
const BUDGET_ALERT_USD = 5.0; // Alert when session spend hits $5

const ai = new NeuroLink({
  providers: [
    { name: "ollama", model: "llama3.1", priority: 1 },
    {
      name: "anthropic",
      model: "claude-3-5-haiku-20241022",
      priority: 2,
      apiKey: process.env.ANTHROPIC_API_KEY,
    },
  ],
  fallback: true,
  fallbackConfig: { timeoutMs: 8000, retryAttempts: 1 },
  middleware: [
    {
      name: "cost-guard",
      onFinish: (result, metadata) => {
        // Ollama cost is effectively zero, but the hook still fires
        const pricing = CLOUD_PRICING[metadata.model] ?? { input: 0, output: 0 };
        const callCost =
          ((result.usage?.promptTokens ?? 0) / 1000) * pricing.input +
          ((result.usage?.completionTokens ?? 0) / 1000) * pricing.output;

        sessionCost += callCost;

        // Always log provider — visibility into fallback frequency is useful
        console.log(
          `[cost-guard] provider=${metadata.provider} ` +
          `model=${metadata.model} ` +
          `tokens=${result.usage?.totalTokens ?? 0} ` +
          `cost=$${callCost.toFixed(6)} ` +
          `session_total=$${sessionCost.toFixed(4)}`
        );

        if (metadata.provider !== "ollama") {
          metrics.increment("ollama.fallback_call", {
            provider: metadata.provider,
          });
        }

        if (sessionCost > BUDGET_ALERT_USD) {
          notifyOps(`Cloud fallback cost alert: $${sessionCost.toFixed(2)} this session`);
        }
      },
    },
  ],
});

Even when Ollama handles the request, this log line tells you your fallback rate. If 30% of requests are hitting cloud fallback, your Ollama instance is undersized for your traffic.

Putting It Together: A Production-Ready Ollama Service

Here's the complete pattern for a service that handles realistic traffic:

import { NeuroLink } from "@juspay/neurolink";

const CLOUD_PRICING = {
  "claude-3-5-haiku-20241022": { input: 0.0008, output: 0.004 },
  "gpt-4o-mini": { input: 0.00015, output: 0.0006 },
};

const bucket = new TokenBucket(10, 2);

export const ai = new NeuroLink({
  providers: [
    { name: "ollama", model: "llama3.1", priority: 1 },
    {
      name: "anthropic",
      model: "claude-3-5-haiku-20241022",
      priority: 2,
      apiKey: process.env.ANTHROPIC_API_KEY,
    },
  ],
  fallback: true,
  fallbackConfig: {
    timeoutMs: 8000,
    retryAttempts: 1,
  },
  middleware: [
    {
      name: "throttle",
      priority: 120,
      transformParams: async (params: any) => {
        if (!bucket.consume()) {
          throw new Error("LOCAL_RATE_LIMIT");
        }
        return params;
      },
    },
    {
      name: "cost-guard",
      onFinish: (result, metadata) => {
        const pricing = (CLOUD_PRICING as any)[metadata.model] ?? { input: 0, output: 0 };
        const cost =
          ((result.usage?.promptTokens ?? 0) / 1000) * pricing.input +
          ((result.usage?.completionTokens ?? 0) / 1000) * pricing.output;

        recordMetrics({
          provider: metadata.provider,
          model: metadata.model,
          tokens: result.usage?.totalTokens ?? 0,
          cost,
          duration: metadata.duration,
          wasLocal: metadata.provider === "ollama",
        });
      },
      onError: (error, metadata) => {
        logger.error("generation_failed", {
          provider: metadata.provider,
          error: error.message,
          recoverable: metadata.recoverable,
        });
      },
    },
  ],
});

export async function generateWithFallback(prompt: string) {
  try {
    return await ai.generate({ input: { text: prompt } });
  } catch (err: any) {
    if (err.message?.startsWith("LOCAL_RATE_LIMIT")) {
      // Explicit queue-full path: skip Ollama entirely, go straight to cloud
      return await new NeuroLink({
        providers: [
          {
            name: "anthropic",
            model: "claude-3-5-haiku-20241022",
            apiKey: process.env.ANTHROPIC_API_KEY,
          },
        ],
      }).generate({ input: { text: prompt } });
    }
    throw err;
  }
}

What to Watch in Production

A few metrics worth tracking:

ollama.fallback_rate: What percentage of requests don't complete on Ollama. Over 10% means your instance is undersized.
ollama.p95_latency: If your 70B model's p95 goes above your timeout threshold, you need a smaller model or more hardware.
cloud_fallback.cost_per_hour: Your actual cloud spend from overflow requests. This is your real Ollama infrastructure cost.
token_bucket.rejection_rate: How often you're hitting the local rate limit before even trying Ollama. A spike here usually means a burst of traffic, not a hardware problem.

The Ollama guide covers what to run. This setup covers what to watch after you run it.

Get started with NeuroLink:

GitHub: https://github.com/juspay/neurolink
npm: npm install @juspay/neurolink
Docs: https://blog.neurolink.ink/docs
Blog: https://blog.neurolink.ink

Building Your Own AI Proxy: Route, Cache, and Monitor LLM Requests in TypeScript

NeuroLink AI — Mon, 06 Apr 2026 10:43:05 +0000

Building Your Own AI Proxy: Route, Cache, and Monitor LLM Requests in TypeScript

In the rapidly evolving world of AI, Large Language Models (LLMs) have become indispensable tools for a myriad of applications. However, integrating and managing these powerful models in production environments comes with its own set of challenges: spiraling costs, vendor lock-in, inconsistent APIs, and a lack of observability. This is where an AI proxy becomes a game-changer.

At Juspay, a fintech company dealing with high-volume, mission-critical transactions, we've learned the hard way that robust infrastructure is paramount. Our experience building and scaling payment systems has directly informed our approach to AI integration, leading to the creation of NeuroLink—our universal AI development platform. NeuroLink isn't just an SDK; it's the foundation upon which you can build sophisticated AI infrastructure, including your own AI proxy.

This article will guide you through the process of building a powerful AI proxy using NeuroLink in TypeScript, covering key components like routing, caching, rate limiting, cost tracking, and logging.

Why Teams Build AI Proxies

Before diving into the "how," let's understand the "why." Why do engineering teams, especially in enterprise environments, invest in building their own AI proxies?

Cost Control and Optimization: LLM usage can get expensive, fast. A proxy allows you to implement intelligent routing to the cheapest available model for a given task, enforce rate limits to prevent accidental overspending, and track costs per user or project.
Multi-Tenancy and Access Control: For platforms serving multiple users or internal teams, a proxy can manage API keys, enforce usage quotas, and isolate access, ensuring fair usage and preventing resource contention.
Vendor Abstraction and Resilience: Relying on a single LLM provider creates vendor lock-in and a single point of failure. A proxy abstracts away provider-specific APIs, allowing you to seamlessly switch between models (e.g., OpenAI, Anthropic, Google Gemini, AWS Bedrock) or even implement failover to a different provider if one goes down. NeuroLink, with its unified API across 13+ providers, makes this abstraction a core feature.
Audit Logs and Observability: Understanding how LLMs are being used is crucial for debugging, compliance, and performance optimization. A proxy acts as a central point to log all requests and responses, track latency, monitor errors, and gain insights into usage patterns.
Data Governance and Security: In sensitive environments, proxies can sanitize requests, redact Personally Identifiable Information (PII) from prompts and responses, and enforce data residency policies.
Performance Enhancement: Caching LLM responses for common or deterministic queries can significantly reduce latency and API calls, improving user experience and cutting costs.

Key Components of an AI Proxy

A robust AI proxy typically comprises several core components:

Request Router: Directs incoming LLM requests to the appropriate provider and model based on predefined rules (e.g., cost, latency, capability).
Caching Layer: Stores responses for frequently asked or deterministic queries to reduce latency and API costs.
Rate Limiting: Prevents abuse and controls spending by limiting the number of requests within a given timeframe.
Cost Tracking: Monitors token usage and API costs, providing granular insights.
Logging and Monitoring: Captures detailed logs of all interactions, errors, and performance metrics.
Security & Data Sanitization: Handles API key management, input validation, and output redaction.

Building One with NeuroLink as the Foundation

NeuroLink is designed to be the "pipe layer for the AI nervous system," making it an ideal foundation for an AI proxy. Its key features—unified API, multi-provider support, middleware system, and built-in telemetry—directly address the needs of proxy development.

Let's explore how to build some of these components using NeuroLink.

Initial Setup

First, ensure you have NeuroLink installed:

npm install @juspay/neurolink

Then, configure your NeuroLink instance with the LLM providers you want to proxy. NeuroLink allows you to define multiple providers and will intelligently select the best one.

// src/proxy.ts
import { NeuroLink, type Middleware } from "@juspay/neurolink";
import { type IncomingMessage, type ServerResponse } from "http";

// Initialize NeuroLink with your desired providers
const neurolink = new NeuroLink({
  // Configure providers with their API keys (ideally from environment variables)
  openai: { apiKey: process.env.OPENAI_API_KEY },
  anthropic: { apiKey: process.env.ANTHROPIC_API_KEY },
  googleAI: { apiKey: process.env.GOOGLE_AI_API_KEY },
  // ... add other providers
});

console.log("NeuroLink AI Proxy initialized.");

// This will be our HTTP server handler
async function handleRequest(req: IncomingMessage, res: ServerResponse) {
  // ... proxy logic goes here
}

// Example of a simple HTTP server (can be integrated with Express, Fastify, etc.)
// import * as http from 'http';
// const server = http.createServer(handleRequest);
// server.listen(3000, () => {
//   console.log('AI Proxy listening on port 3000');
// });

1. Middleware for Logging and Monitoring

NeuroLink's middleware system is perfect for implementing cross-cutting concerns like logging, cost tracking, and performance monitoring.

Let's create a logging middleware:

// src/middleware/logging.ts
import { type Middleware, type GenerateOptions, type GenerateResult } from "@juspay/neurolink";

export const loggingMiddleware: Middleware = {
  name: "logging-middleware",
  async onBeforeGenerate(options: GenerateOptions) {
    const startTime = Date.now();
    console.log(`[${this.name}] Request received:`, {
      model: options.model,
      provider: options.provider,
      input: options.input?.text?.substring(0, 100) + "...", // Log first 100 chars
      // ... other relevant options
    });
    return { ...options, __startTime: startTime }; // Attach startTime for later use
  },
  async onAfterGenerate(result: GenerateResult, options: GenerateOptions & { __startTime: number }) {
    const endTime = Date.now();
    const duration = endTime - options.__startTime;
    console.log(`[${this.name}] Request completed in ${duration}ms:`, {
      model: options.model,
      provider: options.provider,
      output: result.output.text?.substring(0, 100) + "...", // Log first 100 chars
      // ... other relevant results
    });
    // Here, you could send metrics to an observability platform like OpenTelemetry, Langfuse, etc.
    return result;
  },
  async onError(error: Error, options: GenerateOptions) {
    console.error(`[${this.name}] Request failed:`, {
      model: options.model,
      provider: options.provider,
      input: options.input?.text?.substring(0, 100) + "...",
      error: error.message,
    });
    throw error; // Re-throw the error
  },
};

// Apply the middleware to your NeuroLink instance
// neurolink.use(loggingMiddleware);

You can extend this middleware to track token usage (from result.usage), record costs, and send data to your observability platform of choice. NeuroLink also supports OpenTelemetry integration natively.

2. Caching Layer

A caching layer is crucial for optimizing performance and cost. NeuroLink's MCP (Model Context Protocol) enhancements include a built-in ToolCache. While primarily for tool calls, you can adapt a similar pattern for LLM responses or implement a custom middleware.

Here's a simplified caching middleware example:

// src/middleware/caching.ts
import { type Middleware, type GenerateOptions, type GenerateResult } from "@juspay/neurolink";
import LRUCache from "lru-cache"; // npm install lru-cache

interface CacheEntry {
  result: GenerateResult;
  timestamp: number;
}

const cache = new LRUCache<string, CacheEntry>({
  max: 1000, // Max 1000 entries
  ttl: 1000 * 60 * 5, // Cache for 5 minutes
});

export const cachingMiddleware: Middleware = {
  name: "caching-middleware",
  async onBeforeGenerate(options: GenerateOptions) {
    // Generate a cache key based on the request
    const cacheKey = JSON.stringify({
      input: options.input,
      model: options.model,
      provider: options.provider,
      // Exclude non-deterministic options like __startTime
      // You might need a more sophisticated key generation for complex scenarios
    });

    const cached = cache.get(cacheKey);
    if (cached && (Date.now() - cached.timestamp < cache.ttl!)) {
      console.log(`[${this.name}] Cache hit for key: ${cacheKey}`);
      return { ...options, __cachedResult: cached.result }; // Return cached result
    }

    console.log(`[${this.name}] Cache miss for key: ${cacheKey}`);
    return options; // Proceed with generation
  },
  async onAfterGenerate(result: GenerateResult, options: GenerateOptions & { __cachedResult?: GenerateResult }) {
    if (options.__cachedResult) {
      return options.__cachedResult; // Return the result that was found in cache
    }

    // If not from cache, store the new result
    const cacheKey = JSON.stringify({
      input: options.input,
      model: options.model,
      provider: options.provider,
    });
    cache.set(cacheKey, { result, timestamp: Date.now() });
    console.log(`[${this.name}] Stored new result in cache for key: ${cacheKey}`);
    return result;
  },
};

// Add to NeuroLink:
// neurolink.use(cachingMiddleware);

3. Request Router

NeuroLink's core functionality includes intelligent provider selection. You can configure it to automatically pick the cheapest or fastest model, or implement a custom routing logic within a middleware.

For example, to prioritize a specific model or provider for certain requests:

// src/middleware/routing.ts
import { type Middleware, type GenerateOptions } from "@juspay/neurolink";

export const routingMiddleware: Middleware = {
  name: "routing-middleware",
  async onBeforeGenerate(options: GenerateOptions) {
    // Example: Route specific keywords to a powerful but expensive model
    if (options.input?.text?.toLowerCase().includes("financial analysis")) {
      console.log(`[${this.name}] Routing "financial analysis" to gpt-4o.`);
      return { ...options, provider: "openai", model: "gpt-4o" };
    }

    // Example: Route shorter requests to a cheaper, faster model
    if (options.input?.text && options.input.text.length < 50) {
      console.log(`[${this.name}] Routing short request to gemini-3-flash.`);
      return { ...options, provider: "googleAI", model: "gemini-3-flash" };
    }

    // Default NeuroLink's auto-selection or existing provider/model in options
    return options;
  },
};

// neurolink.use(routingMiddleware);

NeuroLink also has a ToolRouter within its MCP enhancements that supports various strategies (e.g., capability-based, round-robin). While this is for tool calls, the principles can be applied to LLM routing.

4. Security: API Key Management & Request Sanitization

Your proxy should manage API keys securely and potentially sanitize user inputs.

For API key management, ensure keys are loaded from secure environment variables or a secrets manager, not hardcoded. NeuroLink handles this by default when you initialize it with process.env.YOUR_API_KEY.

For request sanitization, you can add another middleware:

// src/middleware/sanitization.ts
import { type Middleware, type GenerateOptions } from "@juspay/neurolink";

export const sanitizationMiddleware: Middleware = {
  name: "sanitization-middleware",
  async onBeforeGenerate(options: GenerateOptions) {
    if (options.input?.text) {
      // Simple example: Remove common PII patterns
      let sanitizedText = options.input.text.replace(/\d{16}/g, "[CREDIT_CARD_NUMBER]") // Credit card numbers
                                          .replace(/\b\d{3}-\d{2}-\d{4}\b/g, "[SSN]"); // Social Security Numbers
      // More robust PII detection requires NLP libraries or dedicated services

      // Prevent prompt injection (basic example)
      if (sanitizedText.toLowerCase().includes("ignore previous instructions")) {
        console.warn(`[${this.name}] Potential prompt injection detected. Blocking request.`);
        throw new Error("Invalid input: Potential prompt injection detected.");
      }

      return { ...options, input: { ...options.input, text: sanitizedText } };
    }
    return options;
  },
};

// neurolink.use(sanitizationMiddleware);

When to Build vs. Buy

Building an AI proxy provides ultimate control and customization, which is critical for complex enterprise needs, stringent security requirements, or highly specialized routing logic. However, it requires development and maintenance effort.

For many teams, especially those starting out or with simpler needs, commercial solutions like Portkey, Helicone, OpenPipe, or LiteLLM Proxy offer off-the-shelf capabilities that cover many common proxy use cases (caching, logging, cost tracking). NeuroLink itself can be seen as an SDK that complements these, allowing you to integrate with them or build similar features on top.

Consider building if:

You have unique routing logic or business rules.
You need deep integration with existing internal systems (e.g., identity, billing, audit).
You have strict compliance or security requirements that off-the-shelf solutions don't fully meet.
You want complete control over the infrastructure and data flow.
You are already using NeuroLink for unified AI access and want to leverage its ecosystem.

Consider buying if:

You need a quick, managed solution.
Your requirements are standard (basic caching, rate limiting, logging).
You want to offload infrastructure maintenance.

Conclusion

Building your own AI proxy with NeuroLink in TypeScript empowers you to gain granular control over your LLM infrastructure. From optimizing costs through intelligent routing and caching to enhancing observability with comprehensive logging and ensuring security through input sanitization, a custom proxy addresses the complex challenges of production AI.

By leveraging NeuroLink's unified API and powerful middleware system, you can develop a robust, resilient, and cost-effective AI gateway tailored to your specific needs, enabling your team to build and scale AI applications with confidence.

NeuroLink — The Universal AI SDK for TypeScript

GitHub: github.com/juspay/neurolink
Install: npm install @juspay/neurolink
Docs: docs.neurolink.ink
Blog: blog.neurolink.ink — 150+ technical articles

Why We Built NeuroLink: Making AI Development Practically Free

NeuroLink AI — Mon, 06 Apr 2026 08:39:47 +0000

Why We Built NeuroLink: Making AI Development Practically Free

How a fintech company processing millions of payments ended up building the universal AI SDK—and why we open-sourced it.

The Problem We Couldn't Ignore

At Juspay, we process millions of payments daily across India and Southeast Asia. When you're moving that much money, you don't get to experiment with "nice-to-have" AI features. Every integration has to work, scale, and comply with strict financial regulations.

In 2023, we started integrating AI across our products:

HyperSDK: AI-powered payment error detection and recovery suggestions
Breeze: One-click checkout with intelligent fraud scoring
Euler: AI-assisted merchant analytics and anomaly detection
Lighthouse: Automated alert triaging and root cause analysis

Each product team started their AI integration differently. One team used the OpenAI SDK. Another tried Anthropic. A third experiment used Google's Gemini. By Q2 2024, we had seven different AI integration patterns across our codebase.

Here's what that looked like in practice:

// Team A's OpenAI integration
import OpenAI from "openai";

// Team B's Anthropic integration
import Anthropic from "@anthropic-ai/sdk";

// Team C's Bedrock integration (for compliance)
import { BedrockRuntimeClient } from "@aws-sdk/client-bedrock-runtime";

// Team D's Vertex integration (for PDF processing)
import { VertexAI } from "@google-cloud/vertexai";

Four teams. Four SDKs. Four different error handling patterns. Four different streaming implementations. Four different authentication flows.

And the kicker? They were all doing fundamentally the same thing: sending text to an LLM and getting text back.

The Cost of Fragmentation

Our infrastructure team started seeing the pain first:

Credential Sprawl

Every SDK needed its own API key management. Some used environment variables. Others needed credential files. Bedrock required IAM roles. Vertex needed service account JSON.

Our secrets management system wasn't designed for "one key per AI provider per service." We had API keys scattered across AWS Secrets Manager, HashiCorp Vault, and (we're not proud of this) a few hardcoded in environment configs that we had to rotate in a panic.

Observability Nightmares

Want to know your total AI spend across all providers? Good luck. Each SDK had its own way of exposing token counts. Some didn't expose them at all. We ended up building a Frankenstein monitoring dashboard that queried four different APIs and tried to normalize the data.

When Claude went down for 20 minutes in March 2024, we didn't even know which services were affected because our alerting was fragmented by SDK, not unified by function.

The Onboarding Tax

New engineers joining AI-related projects needed to learn the quirks of whichever SDK that team had chosen. "Oh, you're working on Lighthouse? That's the Anthropic SDK. Here's the 12-page internal doc on how we handle streaming errors."

We were spending more time training people on SDK specifics than on AI concepts that actually mattered.

Provider Lock-In Anxiety

Every architectural decision came with a haunting question: "What if we need to switch providers later?"

OpenAI had an outage. Anthropic changed their API. Gemini launched a feature we needed. Each time, teams hesitated because switching meant rewriting integration code, retesting error handling, and retraining the team.

We weren't choosing the best AI for the job. We were choosing the AI that would minimize migration work.

The Internal Project That Changed Everything

In June 2024, a small team of three engineers got permission to build something experimental: a unified AI client that could route to any provider through a single, consistent API.

The requirements were simple:

One import regardless of which provider you used
Identical error handling across all providers
Automatic failover when a provider went down
Cost optimization without code changes
Full TypeScript safety with IntelliSense support

We called it "NeuroLink"—the idea being that AI intelligence flows like signals through a nervous system, and we needed a unified layer to carry those signals wherever they needed to go.

The Architecture Decisions That Mattered

TypeScript-First (Not TypeScript-Compatible)

Most AI SDKs are written in Python first, with TypeScript bindings added later. The types are often loose. The streaming interfaces feel bolted on.

We built NeuroLink in TypeScript from day one:

// Everything is fully typed
const result = await neurolink.generate({
  input: { text: "Hello" },
  provider: "anthropic",
  model: "claude-3-5-sonnet-20241022", // Autocomplete shows all available models
});

// result is fully typed - content, token counts, finish reason
console.log(result.content);
console.log(result.usage?.inputTokens);

No any types. No "check the documentation for response shape." If it compiles, it works.

Provider-Agnostic by Design

We didn't build an "OpenAI client with fallback." We built a unified protocol that normalizes every provider into a common interface:

// The same code works with any provider
await neurolink.generate({
  input: { text: "Analyze this" },
  provider: "openai",    // GPT-4o
});

await neurolink.generate({
  input: { text: "Analyze this" },
  provider: "anthropic", // Claude
});

await neurolink.generate({
  input: { text: "Analyze this" },
  provider: "vertex",    // Gemini
});

The differences between providers (message format, function calling syntax, error structures) are handled internally. Your code stays clean.

MCP Native from the Start

When we learned about the Model Context Protocol (MCP), we realized it was the missing piece. AI tools shouldn't be tied to a specific provider. They should be infrastructure that any AI can use.

We built MCP support directly into the core:

// Add GitHub as a tool - works with ANY provider
await neurolink.addExternalMCPServer("github", {
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-github"],
  transport: "stdio",
  env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
});

// Claude can use it
await neurolink.generate({
  input: { text: "Create a GitHub issue" },
  provider: "anthropic",
});

// So can GPT-4
await neurolink.generate({
  input: { text: "Create a GitHub issue" },
  provider: "openai",
});

Tools became portable. Teams could share MCP servers across projects without worrying about which LLM was being used.

Intelligent Orchestration

We didn't want engineers to hardcode provider choices. We wanted the system to be smart:

const neurolink = new NeuroLink({
  enableOrchestration: true,
});

// NeuroLink automatically selects the best provider
// based on cost, availability, and task complexity
const result = await neurolink.generate({
  input: { text: "Summarize this legal document" },
  // No provider specified - intelligent routing
});

The orchestration layer considers:

Cost: Use cheaper models for simple tasks
Capability: Route PDF processing to providers with native support
Availability: Fail over automatically during outages
Latency: Choose the fastest provider for real-time features

Engineers stopped thinking about "which provider" and started thinking about "what task."

From Internal Tool to Open Source

By August 2024, NeuroLink was powering AI features across all Juspay products. New integrations that used to take 2-3 weeks were taking 2-3 hours. The math was undeniable.

But we kept thinking: "Every company building with AI is facing this same fragmentation problem."

The decision to open-source wasn't just about being good open-source citizens (though that mattered). It was about creating a standard. If we wanted to hire engineers who already knew NeuroLink, we needed to release it. If we wanted vendors to integrate with our tooling, we needed to be open.

In September 2024, we released NeuroLink on GitHub under the MIT license.

The Impact: Before and After

Here's what changed at Juspay after NeuroLink became our standard:

Metric	Before	After
New AI integration time	2-3 weeks	2-3 hours
Lines of integration code per feature	500+	~50
Provider switch cost	Full rewrite	1 parameter change
Credential management	7 different systems	1 unified config
Onboarding time	3 days (SDK training)	30 minutes
Production incidents (AI-related)	12/quarter	2/quarter

The incident reduction was the surprise benefit. When you have one error handling pattern instead of seven, you get really good at handling those errors.

The Vision: AI Should Be Infrastructure, Not Integration

We're building toward a future where AI is as easy to use as any other infrastructure service.

Think about databases. You don't import pg-sdk, mysql-sdk, and mongo-sdk in the same project. You use an ORM or a query builder that abstracts the differences. You choose PostgreSQL or MySQL based on your needs, not based on which SDK you prefer.

AI should work the same way. The provider is an implementation detail. Your code should focus on the task, not the transport layer.

NeuroLink is our step toward that future:

13+ providers unified under one API
58+ MCP tools that work everywhere
TypeScript-first design for developer confidence
Production-ready features like Redis memory and HITL workflows
Cost optimization that happens automatically

Try What We Built

# Install and setup in under 5 minutes
npm install @juspay/neurolink
npx @juspay/neurolink setup

# Generate with automatic provider selection
npx @juspay/neurolink generate "Hello from NeuroLink"

# Or use it in your TypeScript project
import { NeuroLink } from "@juspay/neurolink";

const neurolink = new NeuroLink();
const result = await neurolink.generate({
  input: { text: "Your prompt here" },
});

From weeks of integration work to hours. From SDK complexity to clean abstraction. From provider lock-in to complete flexibility.

That's why we built NeuroLink. And that's why we think you'll want to use it.

NeuroLink — The Universal AI SDK for TypeScript

GitHub: github.com/juspay/neurolink
Install: npm install @juspay/neurolink
Docs: docs.neurolink.ink
Blog: blog.neurolink.ink — 150+ technical articles

Stop Using 5 Different AI SDKs in Your TypeScript Project

NeuroLink AI — Mon, 06 Apr 2026 08:38:49 +0000

Stop Using 5 Different AI SDKs in Your TypeScript Project

You're creating tech debt for no reason. Here's how to fix it.

Let me guess: your package.json looks something like this right now:

{
  "dependencies": {
    "openai": "^4.0.0",
    "@anthropic-ai/sdk": "^0.24.0",
    "@google/generative-ai": "^0.21.0",
    "@aws-sdk/client-bedrock-runtime": "^3.0.0",
    "@azure/openai": "^2.0.0"
  }
}

Five different SDKs. Five different import styles. Five different response formats. Five different ways to handle streaming. Five different error handling patterns.

And for what? To talk to LLMs that fundamentally do the same thing: take text in, return text out.

You're not being pragmatic. You're being a pack rat, collecting SDKs like they're going out of style. Let's talk about why this is costing you more than you think.

The Real Cost of SDK Fragmentation

Bundle Size Bloating

Each SDK adds weight. OpenAI's SDK alone is ~200KB. Anthropic's is another ~150KB. By the time you've imported all five, you've added nearly a megabyte to your bundle just for HTTP wrappers around JSON APIs.

// Your current bundle impact:
// openai: ~200KB
// @anthropic-ai/sdk: ~150KB
// @google/generative-ai: ~180KB
// @aws-sdk/client-bedrock-runtime: ~300KB
// @azure/openai: ~250KB
// Total: ~1.08MB of SDK overhead

That's before you write a single line of application code.

The Mental Model Tax

Every SDK has its own quirks:

SDK	Streaming Pattern	Error Shape	Auth Method
OpenAI	`for await...of`	`error.message`	`apiKey` param
Anthropic	`stream.on()`	`error.error.message`	`anthropicApiKey` header
Google AI	`async generator`	`error.message`	`genAI.getGenerativeModel()`
Bedrock	`response.body`	SDK-specific	AWS credentials
Azure	`stream.iterator()`	Nested error	`azureApiKey` + endpoint

You need to remember which is which. Your team needs documentation for each. Code reviews become a game of "did you handle the Anthropic error format correctly this time?"

Inconsistent Error Handling

Here's what error handling looks like across different SDKs:

// OpenAI
try {
  const response = await openai.chat.completions.create({...});
} catch (error) {
  // error is an APIError with nested props
  console.log(error.message);
  console.log(error.code); // rate_limit_exceeded, etc.
}

// Anthropic
try {
  const response = await anthropic.messages.create({...});
} catch (error) {
  // error is an AnthropicError
  // need error.error for details
  console.log(error.error?.message);
  console.log(error.error?.type); // rate_limit_error, etc.
}

// Google AI
try {
  const result = await model.generateContentStream(...);
} catch (error) {
  // Google wraps errors differently
  console.log(error.message);
  // No standardized error codes
}

You end up writing adapter layers anyway. So why not use one that's already built?

Testing Multiplies

Every SDK needs its own test setup. Mocking OpenAI responses? Different from mocking Anthropic. Testing streaming? Five different patterns to validate. Integration tests? You need real credentials for each provider.

Your CI pipeline thanks you for the complexity.

The Provider Switching Myth

"But I need to support multiple providers for redundancy!"

Sure. But you don't need five SDKs for that. You need one SDK that understands how to route between providers. The abstraction should happen at the integration layer, not in your application code.

Here's what "provider redundancy" looks like with multiple SDKs:

// The nightmare you wrote
async function generateWithFallback(prompt: string) {
  try {
    return await callOpenAI(prompt);
  } catch (e) {
    console.log("OpenAI failed, trying Anthropic...");
    try {
      return await callAnthropic(prompt);
    } catch (e) {
      console.log("Anthropic failed, trying Google...");
      return await callGoogle(prompt);
    }
  }
}

Nested try-catch hell. Hardcoded fallback order. No cost optimization. No intelligent routing. Just desperation-driven retry logic.

The Unified Alternative

What if you could do this instead?

import { NeuroLink } from "@juspay/neurolink";

const neurolink = new NeuroLink();

// Works with any provider - same API
const result = await neurolink.generate({
  input: { text: "Explain quantum computing" },
  provider: "openai", // or "anthropic", "vertex", "bedrock", "azure"...
});

console.log(result.content);

That's it. Same code. Same error handling. Same streaming pattern. Just change one parameter to switch providers.

Streaming: One Pattern, Every Provider

Remember the streaming chaos? Here's what unified streaming looks like:

import { NeuroLink } from "@juspay/neurolink";

const neurolink = new NeuroLink();

// Same streaming pattern for ALL 13 providers
const result = await neurolink.stream({
  input: { text: "Write a story" },
  provider: "anthropic", // or any other provider
});

for await (const chunk of result.stream) {
  if ("content" in chunk) {
    process.stdout.write(chunk.content);
  }
}

No more memorizing stream.on('data') vs for await...of vs response.body.pipe(). One pattern. Every provider.

Automatic Provider Fallback (That Actually Works)

const neurolink = new NeuroLink({
  enableOrchestration: true, // Smart routing + failover
});

// NeuroLink automatically:
// 1. Selects the optimal provider
// 2. Falls back if one fails
// 3. Optimizes for cost when appropriate
const result = await neurolink.generate({
  input: { text: "Analyze this data" },
  // No provider specified - intelligent auto-selection
});

No nested try-catch. No manual failover logic. No hardcoded provider preferences. Just intelligent routing that works.

The Bundle Size Reality Check

NeuroLink: ~150KB total for 13+ providers.

Your current setup: ~1MB+ for 5 providers.

And with NeuroLink, adding provider #6, #7, #13 costs you zero additional bundle size. The provider routing happens server-side or through a unified client. You're not importing SDK bloat for providers you might use once a month.

Error Handling That Makes Sense

import { NeuroLink } from "@juspay/neurolink";

const neurolink = new NeuroLink();

try {
  const result = await neurolink.generate({
    input: { text: "Hello" },
    provider: "openai",
  });
} catch (error) {
  // Same error structure regardless of provider
  console.log(error.message);
  console.log(error.provider); // Which provider failed
  console.log(error.code); // Standardized error codes
  console.log(error.retryable); // Can we retry?
}

One error format. Standardized codes. Provider-agnostic handling. Your error monitoring tools will thank you.

Tools Without the Configuration Tax

Adding tools to OpenAI vs Anthropic? Different parameter structures. Different function calling formats. Different response parsing.

With NeuroLink:

import { NeuroLink } from "@juspay/neurolink";

const neurolink = new NeuroLink({
  tools: [
    {
      name: "getWeather",
      description: "Get weather for a location",
      parameters: {
        type: "object",
        properties: {
          location: { type: "string" },
        },
      },
      execute: async ({ location }) => {
        return await fetchWeather(location);
      },
    },
  ],
});

// Works identically across all providers
const result = await neurolink.generate({
  input: { text: "What's the weather in Tokyo?" },
  provider: "vertex", // or "anthropic", "bedrock", etc.
});

One tool definition. Universal compatibility. No provider-specific format conversions.

MCP: The Tool Ecosystem You Didn't Know You Needed

NeuroLink ships with 6 built-in tools and supports 58+ external MCP servers:

// GitHub MCP server - works across all providers
await neurolink.addExternalMCPServer("github", {
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-github"],
  transport: "stdio",
  env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
});

// Now AI can create issues, list repos, create PRs
const result = await neurolink.generate({
  input: { text: 'Create a GitHub issue for this bug' },
  provider: "anthropic", // MCP works with any provider
});

Your tools aren't tied to a provider. They're infrastructure.

What You're Actually Defending

When you say "I need separate SDKs for flexibility," what you're actually saying is:

"I enjoy writing adapter code"
"I like debugging why Anthropic's error format broke my handler again"
"Bundle size doesn't matter" (it does)
"My team enjoys context-switching between 5 documentation sites"
"I prefer writing 5 different test mocks"

You're not preserving flexibility. You're preserving complexity for its own sake.

The Migration Path

"But I already have code using these SDKs!"

Fine. Keep it. But ask yourself: every new feature you build, every new AI integration you add—do you want to keep multiplying your SDK dependencies? Or do you want to consolidate?

// Legacy code - keep it working
import OpenAI from "openai";
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// New code - use NeuroLink
import { NeuroLink } from "@juspay/neurolink";
const neurolink = new NeuroLink();

// Gradually migrate. No big-bang rewrite required.

Start new features with NeuroLink. Migrate legacy code when you touch it. In 6 months, you'll wonder why you ever managed five SDKs.

The Hard Truth

The AI landscape is consolidating. Providers are becoming commodities. The value isn't in which LLM you use—it's in how you use them.

Your job isn't to be an expert in OpenAI's SDK quirks or Anthropic's response format. Your job is to build products that solve problems. Every hour spent debugging SDK differences is an hour not spent on your actual product.

Stop collecting SDKs like Pokémon cards. Start building with a unified platform.

Try It In 30 Seconds

# Install once, get 13+ providers
npm install @juspay/neurolink

# Run the setup wizard (configures your API keys)
npx @juspay/neurolink setup

# Generate with any provider
npx @juspay/neurolink generate "Hello world" --provider openai
npx @juspay/neurolink generate "Hello world" --provider anthropic
npx @juspay/neurolink generate "Hello world" --provider vertex

Same command. Same interface. Different providers. Zero cognitive overhead.

NeuroLink — The Universal AI SDK for TypeScript

GitHub: github.com/juspay/neurolink
Install: npm install @juspay/neurolink
Docs: docs.neurolink.ink
Blog: blog.neurolink.ink — 150+ technical articles

Building a Slack AI Assistant with NeuroLink: From Prototype to Production

NeuroLink AI — Mon, 06 Apr 2026 08:37:49 +0000

Building a Slack AI Assistant with NeuroLink: From Prototype to Production

Internal support consumes engineering time. At Juspay, our 500+ engineers constantly asked questions like:

"What's the status of the Euler payment API?"
"How do I get credentials for the sandbox environment?"
"Who owns the HyperSDK Android module?"
"Deploy the latest Breeze release to staging"

These questions needed answers, but pulling engineers from deep work was expensive. We needed an AI assistant that could:

Answer questions using our internal knowledge
Execute actions (deployments, credential provisioning)
Remember conversation context across sessions
Integrate with our existing tools (Jira, Bitbucket, Kubernetes)

Meet Tara — our Slack AI assistant built with NeuroLink and Claude Sonnet.

Architecture Overview

┌──────────────┐     ┌──────────────┐     ┌─────────────────┐
│   Slack      │────▶│  Slack Bolt  │────▶│   Tara Service  │
│   Message    │     │   App        │     │   (FastAPI)     │
└──────────────┘     └──────────────┘     └────────┬────────┘
                                                   │
                          ┌────────────────────────┼────────────────────────┐
                          ▼                        ▼                        ▼
                   ┌──────────────┐      ┌─────────────────┐      ┌──────────────┐
                   │  NeuroLink   │      │  MCP Servers    │      │   Redis      │
                   │  SDK         │      │  - Jira         │      │   Memory     │
                   │  (Claude)    │      │  - Bitbucket    │      │              │
                   └──────────────┘      │  - K8s          │      └──────────────┘
                                          └─────────────────┘

Getting Started: The Prototype

Our first version was surprisingly simple. Here's the core loop:

import { NeuroLink } from "@juspay/neurolink";
import { App } from "@slack/bolt";

// Initialize NeuroLink with Claude
const neurolink = new NeuroLink({
  conversationMemory: {
    enabled: true,
    enableSummarization: true, // Auto-summarize long conversations
  },
});

// Slack Bolt app
const slack = new App({
  token: process.env.SLACK_BOT_TOKEN,
  signingSecret: process.env.SLACK_SIGNING_SECRET,
});

// Handle direct messages and mentions
slack.event("app_mention", async ({ event, say }) => {
  await handleMessage(event.user, event.text, say);
});

slack.event("message", async ({ event, say }) => {
  if (event.channel_type === "im") {
    await handleMessage(event.user, event.text, say);
  }
});

Conversation Handling with Memory

The magic of Tara is maintaining context. NeuroLink's conversation memory handles this automatically:

async function handleMessage(
  userId: string,
  text: string,
  say: (text: string) => Promise<void>
) {
  // Stream the response for better UX
  const result = await neurolink.stream({
    input: { text },
    provider: "anthropic",
    model: "claude-4-sonnet",
    user: userId, // Enables per-user memory automatically
    system: `You are Tara, Juspay's AI assistant. You help engineers with:
             - Finding documentation and code
             - Checking deployment status
             - Answering questions about services
             - Creating Jira tickets and PRs

             Be concise and helpful. If you need to take action,
             use the available tools.`,
    enableOrchestration: true, // Allow tool use
  });

  // Stream chunks back to Slack
  let response = "";
  for await (const chunk of result.stream) {
    if ("content" in chunk) {
      response += chunk.content;
      // Update Slack message every few tokens
      if (response.length % 100 === 0) {
        await say(response + "⏳");
      }
    }
  }

  await say(response);
}

Adding Tool Capabilities

Tara becomes powerful when she can actually do things. We added MCP servers for our internal tools:

// Jira integration for ticket creation
await neurolink.addExternalMCPServer("jira", {
  transport: "stdio",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-jira"],
  env: {
    JIRA_TOKEN: process.env.JIRA_TOKEN,
    JIRA_HOST: "https://juspay.atlassian.net",
  },
});

// Kubernetes for deployment status
await neurolink.addExternalMCPServer("k8s", {
  transport: "stdio",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-kubernetes"],
});

// Internal API server (custom MCP)
await neurolink.addExternalMCPServer("juspay-api", {
  transport: "http",
  url: "https://internal-api.juspay.net/mcp",
  headers: {
    Authorization: `Bearer ${process.env.INTERNAL_API_TOKEN}`,
  },
});

Now users can say things like:

"Create a Jira ticket for the HyperSDK crash on Android"

And Tara will:

Use the Jira tool to create the ticket
Return the ticket URL
Remember the ticket ID for follow-up questions

Structured Commands with Zod

For common operations, we use structured output to ensure reliability:

const DeploymentRequest = z.object({
  service: z.enum(["euler", "breeze", "hyper-sdk", "neurolink"]),
  environment: z.enum(["dev", "staging", "prod"]),
  version: z.string(),
  confirm: z.boolean(),
});

async function handleDeploymentRequest(userId: string, text: string) {
  const result = await neurolink.generate({
    input: {
      text: `Parse this deployment request: "${text}"`,
    },
    provider: "anthropic",
    model: "claude-4-haiku",
    schema: DeploymentRequest,
    output: { format: "json" },
  });

  const deployment = result.parsed as z.infer<typeof DeploymentRequest>;

  if (!deployment.confirm) {
    return `You want to deploy ${deployment.service} v${deployment.version} to ${deployment.environment}. Confirm with "yes"?`;
  }

  // Execute deployment via MCP
  await neurolink.generate({
    input: {
      text: `Deploy ${deployment.service} version ${deployment.version} to ${deployment.environment}`,
    },
  });

  return `✅ Deployment initiated for ${deployment.service} v${deployment.version} to ${deployment.environment}`;
}

Multi-Modal Support: Screenshots and Logs

Engineers often share screenshots of errors or paste log snippets. Tara handles these with NeuroLink's multimodal capabilities:

slack.event("message", async ({ event, say }) => {
  if (event.files && event.files.length > 0) {
    // Download files
    const filePaths = await downloadSlackFiles(event.files);

    const result = await neurolink.generate({
      input: {
        text: "What's in this screenshot? If it's an error, suggest fixes.",
        files: filePaths,
      },
      provider: "google-ai",
      model: "gemini-2.5-pro", // Vision-capable model
    });

    await say(result.content);
  }
});

Advanced Features

1. RAG for Documentation

Tara answers questions about our internal docs using RAG:

const answer = await neurolink.generate({
  input: { text: "How does the Euler payment flow work?" },
  rag: {
    files: [
      "./docs/euler/architecture.md",
      "./docs/euler/payment-flow.md",
      "./docs/euler/webhooks.md",
    ],
    strategy: "markdown",
    topK: 5,
  },
});

2. Human-in-the-Loop for Sensitive Actions

For destructive operations, we require approval:

const neurolink = new NeuroLink({
  hitl: {
    enabled: true,
    requireApproval: ["deployToProduction", "deleteDatabase", "revokeCredentials"],
    reviewCallback: async (action, context) => {
      // Post to admin Slack channel for approval
      return await requestSlackApproval(action, context.user);
    },
  },
});

3. Cost Optimization with Model Routing

We use different models for different tasks:

// Simple queries: fast, cheap model
const quickAnswer = await neurolink.generate({
  input: { text: "What time is it in Bangalore?" },
  provider: "google-ai",
  model: "gemini-2.5-flash",
});

// Complex analysis: reasoning model
const architectureReview = await neurolink.generate({
  input: { text: "Review this system design..." },
  provider: "anthropic",
  model: "claude-4-opus",
  thinkingConfig: { thinkingLevel: "high" },
});

Production Deployment

We run Tara as a containerized service with the following configuration:

// production-config.ts
export const taraConfig = {
  neurolink: {
    conversationMemory: {
      enabled: true,
      redisConfig: {
        host: process.env.REDIS_HOST,
        port: 6379,
        ttl: 86400 * 30, // 30-day retention
      },
    },
    // Multi-provider failover
    fallbackProviders: ["anthropic", "google-ai", "vertex"],
  },
  slack: {
    port: 3000,
    logLevel: "info",
  },
  // Rate limiting per user
  rateLimit: {
    requestsPerMinute: 20,
    burstSize: 5,
  },
};

Results

After deploying Tara to our engineering organization:

Metric	Before	After
Avg. support response time	4 hours	30 seconds
Tickets created correctly	N/A	98%
Engineer satisfaction	65%	92%
Cost per interaction	$2.50 (human)	$0.03 (AI)

Key Learnings

Conversation memory is essential: Users expect context continuity. Redis-backed memory made Tara feel truly intelligent.
Streaming improves perception: Even if total time is the same, streaming responses feel faster and more engaging.
Tool use requires guardrails: Start with read-only tools, add write operations gradually with HITL.
Model selection matters: Routing simple queries to cheaper models cut costs by 75% without quality loss.
MCP > Custom integrations: Using standard MCP servers for Jira, K8s, etc. meant we spent days, not weeks, on integrations.

Getting Started

Want to build your own Slack assistant? Here's the minimal setup:

import { NeuroLink } from "@juspay/neurolink";
import { App } from "@slack/bolt";

const neurolink = new NeuroLink({
  conversationMemory: { enabled: true },
});

const slack = new App({
  token: process.env.SLACK_BOT_TOKEN,
  signingSecret: process.env.SLACK_SIGNING_SECRET,
});

slack.event("message", async ({ event, say }) => {
  const result = await neurolink.stream({
    input: { text: event.text },
    provider: "anthropic",
    model: "claude-4-sonnet",
    user: event.user,
  });

  let response = "";
  for await (const chunk of result.stream) {
    if ("content" in chunk) response += chunk.content;
  }
  await say(response);
});

await slack.start(3000);

Conclusion

Building Tara with NeuroLink let us create a production-ready AI assistant in days, not months. The combination of Claude's reasoning, NeuroLink's memory management, and MCP's tool ecosystem gave us everything we needed to automate internal support at scale.

If you're considering an internal AI assistant, start with NeuroLink — the unified API means you can experiment with different models and tools without rewriting your integration code.

NeuroLink — The Universal AI SDK for TypeScript

GitHub: github.com/juspay/neurolink
Install: npm install @juspay/neurolink
Docs: docs.neurolink.ink
Blog: blog.neurolink.ink — 150+ technical articles

How We Built an AI Code Reviewer with NeuroLink and Bitbucket

NeuroLink AI — Mon, 06 Apr 2026 08:36:50 +0000

How We Built an AI Code Reviewer with NeuroLink and Bitbucket

At Juspay, we process thousands of pull requests across 100+ repositories every month. Code review bottlenecks were slowing our release velocity, and we needed a solution that could:

Understand our domain-specific patterns and conventions
Integrate seamlessly with Bitbucket and Jira
Learn from past reviews to improve over time
Run entirely within our infrastructure for security

Enter Yama — our AI-native code review tool built on NeuroLink, the universal AI SDK for TypeScript. This is the story of how we built it.

The Architecture Decision

We evaluated several approaches:

Off-the-shelf AI code review tools: Great for generic checks, but couldn't understand our Haskell payment systems or custom conventions
Direct LLM API integration: Would require building provider abstraction, memory management, and tool integration from scratch
NeuroLink with MCP: Best of both worlds — provider flexibility + standardized tool integration

We chose NeuroLink because it gave us:

13 AI providers under one API (we use Claude for reasoning, Gemini for cost-effective checks)
MCP (Model Context Protocol) for Bitbucket/Jira integration
Conversation memory for learning reviewer preferences
Streaming responses for real-time progress updates

Core Architecture

┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Bitbucket PR   │────▶│   Yama API   │────▶│   NeuroLink     │
│   Webhook       │     │   (Node.js)  │     │   SDK           │
└─────────────────┘     └──────────────┘     └────────┬────────┘
       │                                              │
       ▼                                              ▼
┌─────────────────┐                         ┌─────────────────┐
│  Jira Issues    │                         │  MCP Servers    │
│  (context)      │                         │  - Bitbucket    │
│                 │                         │  - Jira         │
└─────────────────┘                         └─────────────────┘

Building the Review Pipeline

1. Setting Up NeuroLink with MCP Integration

First, we initialize NeuroLink with our MCP servers for Bitbucket and Jira:

import { NeuroLink } from "@juspay/neurolink";

const neurolink = new NeuroLink({
  conversationMemory: {
    enabled: true,
    redisConfig: {
      host: process.env.REDIS_HOST,
      port: 6379,
      ttl: 86400 * 7, // Keep PR context for a week
    },
  },
});

// Connect to Bitbucket MCP server
await neurolink.addExternalMCPServer("bitbucket", {
  transport: "stdio",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-bitbucket"],
  env: {
    BITBUCKET_TOKEN: process.env.BITBUCKET_TOKEN,
    BITBUCKET_WORKSPACE: "juspay",
  },
});

// Connect to Jira for ticket context
await neurolink.addExternalMCPServer("jira", {
  transport: "stdio",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-jira"],
  env: {
    JIRA_TOKEN: process.env.JIRA_TOKEN,
    JIRA_HOST: "https://juspay.atlassian.net",
  },
});

2. Fetching PR Context

When a webhook fires, we gather all relevant context:

interface PRContext {
  prId: string;
  repoSlug: string;
  branch: string;
  author: string;
  jiraTicket?: string;
}

async function gatherPRContext(
  neurolink: NeuroLink,
  ctx: PRContext
): Promise<string> {
  // Let the AI use MCP tools to fetch PR data
  const result = await neurolink.generate({
    input: {
      text: `Fetch the diff, files changed, and description for PR ${ctx.prId}
             in repo ${ctx.repoSlug}. Also fetch related Jira ticket ${ctx.jiraTicket}.`,
    },
    provider: "anthropic",
    model: "claude-4-sonnet",
    enableOrchestration: true, // Let AI decide which tools to call
  });

  return result.content;
}

3. The Multi-Stage Review Engine

Yama performs reviews in three stages, each with different models for cost optimization:

async function performCodeReview(
  neurolink: NeuroLink,
  prContext: string,
  files: string[]
): Promise<ReviewComment[]> {
  const comments: ReviewComment[] = [];

  // Stage 1: Security scan (fast, cheap model)
  const securityResult = await neurolink.generate({
    input: {
      text: `Analyze this PR for security issues:
             ${prContext}

             Check for:
             - Hardcoded secrets or credentials
             - SQL injection vulnerabilities
             - Unsafe file operations
             - Authentication bypasses`,
    },
    provider: "google-ai",
    model: "gemini-2.5-flash", // Fast and cost-effective
    schema: z.object({
      issues: z.array(z.object({
        severity: z.enum(["critical", "high", "medium", "low"]),
        file: z.string(),
        line: z.number(),
        description: z.string(),
        suggestion: z.string(),
      })),
    }),
    output: { format: "json" },
  });

  comments.push(...parseSecurityIssues(securityResult));

  // Stage 2: Architecture review (reasoning model)
  const archResult = await neurolink.stream({
    input: {
      text: `Review this PR for architectural concerns:
             ${prContext}

             Consider our conventions:
             - Haskell services should use EulerHS patterns
             - Database queries must use Beam ORM
             - API responses follow Juspay standard format`,
      files: files.filter(f => f.endsWith(".hs") || f.endsWith(".ts")),
    },
    provider: "anthropic",
    model: "claude-4-sonnet",
    thinkingConfig: {
      thinkingLevel: "medium", // Enable extended reasoning
    },
  });

  // Stream architecture review in real-time
  for await (const chunk of archResult.stream) {
    if ("content" in chunk) {
      process.stdout.write(chunk.content);
    }
  }

  // Stage 3: Style and conventions (cached model)
  const styleResult = await neurolink.generate({
    input: {
      text: `Check style compliance. Be concise.`,
      files: files,
    },
    provider: "google-ai",
    model: "gemini-2.5-flash",
    rag: {
      files: ["./docs/coding-standards.md", "./docs/style-guide.md"],
      strategy: "markdown",
      topK: 3,
    },
  });

  return comments;
}

4. Posting Review Comments

Using the Bitbucket MCP tool to post comments:

async function postReviewComments(
  neurolink: NeuroLink,
  prId: string,
  comments: ReviewComment[]
) {
  for (const comment of comments) {
    await neurolink.generate({
      input: {
        text: `Post this review comment to PR ${prId}:
               File: ${comment.file}
               Line: ${comment.line}
               Comment: ${comment.description}

               ${comment.suggestion ? `Suggestion: ${comment.suggestion}` : ""}`,
      },
      provider: "anthropic",
      // MCP tool will be automatically invoked
    });
  }
}

Learning from Feedback

Yama improves over time by learning from developer feedback. When a reviewer dismisses or modifies a Yama comment, we capture that signal:

async function learnFromFeedback(
  neurolink: NeuroLink,
  originalComment: ReviewComment,
  reviewerAction: "accepted" | "modified" | "dismissed",
  reviewerNote?: string
) {
  // Store feedback in Redis memory for future context
  await neurolink.generate({
    input: {
      text: `Learning from review feedback:
             Original: ${originalComment.description}
             Action: ${reviewerAction}
             Note: ${reviewerNote || "None"}

             Adjust future recommendations accordingly.`,
    },
    provider: "anthropic",
    model: "claude-4-haiku",
  });
}

Results & Lessons Learned

After 6 months in production:

70% reduction in trivial review comments (style, formatting)
40% faster PR turnaround time
Zero security issues missed in production (caught during review)
$0.12 average cost per PR review (using cost-optimized model routing)

Key Lessons

Multi-model strategy works: Using cheaper models for simple checks and expensive ones for complex reasoning cut costs by 80%
MCP is a game-changer: Tool integration that "just works" across providers saved us weeks of integration work
Memory matters: Per-PR conversation context dramatically improved review quality over stateless approaches
Streaming UX: Real-time progress updates made developers trust the system more

The Code

Yama is now part of our internal tooling suite. Here's the complete minimal setup if you want to build something similar:

import { NeuroLink } from "@juspay/neurolink";
import { z } from "zod";

// Initialize
const yama = new NeuroLink({
  conversationMemory: { enabled: true },
});

// Add your MCP servers
await yama.addExternalMCPServer("bitbucket", {
  transport: "stdio",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-bitbucket"],
  env: { BITBUCKET_TOKEN: process.env.BITBUCKET_TOKEN },
});

// Review webhook handler
export async function handlePRWebhook(payload: PRWebhook) {
  const context = await gatherPRContext(yama, payload);
  const comments = await performCodeReview(yama, context, payload.files);
  await postReviewComments(yama, payload.prId, comments);
}

Conclusion

Building Yama with NeuroLink let us focus on the review logic instead of AI infrastructure. The combination of provider flexibility, MCP tool integration, and conversation memory made it possible to ship a production-grade code review system in weeks, not months.

If you're building AI-powered developer tools, NeuroLink's unified API and MCP ecosystem will save you significant engineering time — it certainly did for us.

NeuroLink — The Universal AI SDK for TypeScript

GitHub: github.com/juspay/neurolink
Install: npm install @juspay/neurolink
Docs: docs.neurolink.ink
Blog: blog.neurolink.ink — 150+ technical articles

Semantic Search with TypeScript: Using embed() and embedMany() for Vector Search

NeuroLink AI — Mon, 06 Apr 2026 08:35:51 +0000

Semantic Search with TypeScript: Using embed() and embedMany() for Vector Search

In the age of information overload, keyword-based search often falls short. Users aren't just looking for exact matches; they're looking for meaning. This is where semantic search shines, allowing systems to understand the intent behind a query and retrieve results that are conceptually similar, even if they don't contain the exact keywords.

At the heart of semantic search lies the concept of embeddings – dense numerical representations of text that capture its meaning. NeuroLink, the universal AI SDK for TypeScript, simplifies the process of generating and utilizing these embeddings, making it straightforward to build powerful semantic search capabilities into your applications.

This article will guide you through generating embeddings with NeuroLink's embed() and embedMany() methods, performing similarity search, and integrating with vector databases to build a complete semantic search engine.

What are Embeddings and Why Are They Crucial for Semantic Search?

Imagine mapping every word, sentence, or document into a multi-dimensional space where items with similar meanings are located closer to each other. That's essentially what an embedding model does. Each piece of text is transformed into a fixed-size vector (a list of numbers) that encapsulates its semantic properties.

For semantic search, this means:

Understanding Context: A search for "car repair" can return results about "automobile maintenance" or "vehicle servicing" even if the exact phrase isn't present.
Ranking Relevance: Results can be ranked based on their semantic similarity to the query, providing more relevant outcomes.
Bridging Vocabulary Gaps: It overcomes issues arising from synonyms, paraphrases, or different ways of expressing the same idea.

NeuroLink provides a unified API to generate these crucial vectors from various leading AI providers.

Generating Embeddings with NeuroLink: `embed()` and `embedMany()`

NeuroLink offers two primary methods for generating embeddings via its ProviderFactory interface: embed() for single text strings and embedMany() for efficient batch processing.

`provider.embed(text, modelName?)`: Single Text Embedding

The embed() method takes a single string of text and returns its corresponding embedding vector.

import { ProviderFactory } from "@juspay/neurolink";

async function getEmbedding(text: string) {
  // Create an OpenAI provider instance for embedding.
  // NeuroLink supports OpenAI, Google AI Studio, Google Vertex, and Amazon Bedrock for embeddings.
  const provider = await ProviderFactory.createProvider("openai");

  // Generate the embedding vector
  const vector = await provider.embed(text);

  console.log(`Text: "${text}"`);
  console.log(`Embedding dimension: ${vector.length}`);
  // console.log("Embedding vector (first 5 elements):", vector.slice(0, 5));

  return vector;
}

// Example usage
const queryEmbedding = await getEmbedding("How do I reset my password?");
const documentEmbedding = await getEmbedding("Troubleshooting password issues");

Key Parameters:

text (string, required): The input text to be embedded.
modelName (string, optional): Allows you to override the default embedding model for the chosen provider. For example, text-embedding-3-small for OpenAI or gemini-embedding-001 for Google AI Studio.

`provider.embedMany(texts, modelName?)`: Batch Embedding for Efficiency

For scenarios involving multiple documents or a large corpus, embedMany() is significantly more efficient. It accepts an array of text strings and returns an array of corresponding embedding vectors. NeuroLink (via Vercel AI SDK) intelligently handles batching for providers that have batch size limits.

import { ProviderFactory } from "@juspay/neurolink";

async function getManyEmbeddings(texts: string[]) {
  const provider = await ProviderFactory.createProvider("googleAiStudio");

  // Generate embeddings for multiple texts in a single API call
  const embeddings = await provider.embedMany(texts);

  console.log(`Generated ${embeddings.length} embeddings.`);
  embeddings.forEach((emb, index) => {
    console.log(`Embedding ${index + 1} dimension: ${emb.length}`);
  });

  return embeddings;
}

// Example usage with multiple document snippets
const documents = [
  "NeuroLink provides a unified API for 13+ AI providers.",
  "Semantic search helps find documents by meaning, not just keywords.",
  "Event-driven AI applications can leverage lifecycle hooks for analytics.",
];

const documentEmbeddings = await getManyEmbeddings(documents);

Key Parameters:

texts (string[], required): An array of text strings to be embedded.
modelName (string, optional): Same as embed(), allows overriding the default embedding model.

Supported Providers and Model Selection

NeuroLink integrates with several top-tier embedding providers:

OpenAI: Uses models like text-embedding-3-small (default) or text-embedding-3-large.
Google AI Studio: Uses gemini-embedding-001 (default).
Google Vertex: Uses text-embedding-004 (default).
Amazon Bedrock: Uses models like amazon.titan-embed-text-v2:0 (default).

You can configure the default models using environment variables (e.g., OPENAI_EMBEDDING_MODEL, VERTEX_EMBEDDING_MODEL) or directly within the embed()/embedMany() calls.

For providers that do not natively support embeddings (e.g., Anthropic, Mistral), you can still use NeuroLink for text generation and then use a separate NeuroLink provider instance configured for an embedding-capable provider to handle your embedding needs.

import { ProviderFactory } from "@juspay/neurolink";

// Use Anthropic for chat generation
const chatProvider = await ProviderFactory.createProvider("anthropic");
const response = await chatProvider.generate({
  input: { text: "Tell me a story about a wizard." },
});

// Use OpenAI for embeddings, independently
const embedProvider = await ProviderFactory.createProvider("openai");
const storyEmbedding = await embedProvider.embed(response.text);

Building a Semantic Search Engine: From Embeddings to Vector Databases

Once you have embeddings, the next step is to store them and perform similarity searches. This typically involves a vector database (or vector store), which is optimized for storing and querying high-dimensional vectors.

The general workflow for building a semantic search engine looks like this:

Index Documents:
- Take your corpus of documents (e.g., articles, product descriptions, support tickets).
- Chunk them into manageable segments if they are large.
- Use embedMany() to generate embeddings for each segment.
- Store these embeddings, along with their original text and any metadata, in a vector database.
Query and Retrieve:
- When a user submits a query, use embed() to generate an embedding for the query.
- Query the vector database to find document embeddings that are most "similar" to the query embedding. Similarity is usually calculated using distance metrics like cosine similarity.
- Retrieve the original text segments corresponding to the most similar embeddings.

Practical Code Example: In-Memory Semantic Search

Let's illustrate with a basic in-memory vector store, focusing on the core embedding and similarity logic. For production systems, you would integrate with dedicated vector databases like Pinecone, Weaviate, or ChromaDB.

import { NeuroLink, ProviderFactory, InMemoryVectorStore } from "@juspay/neurolink";

// 1. Prepare your documents
const articles = [
  { id: "article1", text: "NeuroLink simplifies AI integration across 13 providers." },
  { id: "article2", text: "Vector embeddings enable semantic search by capturing meaning." },
  { id: "article3", text: "Lifecycle hooks in NeuroLink's middleware system manage AI events." },
  { id: "article4", text: "Building reactive applications with event-driven AI architectures." },
  { id: "article5", text: "The importance of cost tracking and analytics in AI applications." },
];

async function buildSemanticSearchEngine() {
  const embedProvider = await ProviderFactory.createProvider("openai");
  const vectorStore = new InMemoryVectorStore(); // For simplicity, use in-memory

  // 2. Generate embeddings and index documents
  console.log("Indexing documents...");
  const textsToEmbed = articles.map((a) => a.text);
  const embeddings = await embedProvider.embedMany(textsToEmbed);

  const documentNodes = articles.map((article, index) => ({
    id: article.id,
    vector: embeddings[index],
    metadata: { text: article.text },
  }));
  await vectorStore.upsert("docs_index", documentNodes); // Store embeddings in an index
  console.log("Documents indexed successfully.");

  // Function to perform semantic search
  async function semanticSearch(query: string, topK: number = 2) {
    console.log(`Searching for: "${query}"`);
    const queryVector = await embedProvider.embed(query);

    // 3. Query the vector store for similar documents
    const searchResults = await vectorStore.query("docs_index", queryVector, topK);

    console.log("Top results:");
    searchResults.forEach((result, i) => {
      console.log(
        `  ${i + 1}. Score: ${result.score.toFixed(4)}, Text: "${result.metadata.text}"`
      );
    });
    return searchResults;
  }

  // 4. Test the semantic search engine
  await semanticSearch("How to connect to multiple AI services?");
  await semanticSearch("Tell me about application events in AI.");
}

buildSemanticSearchEngine().catch(console.error);

Integration with RAG Pipelines

NeuroLink's rag feature simplifies the entire process by internally handling document chunking, embedding generation, and similarity search. When you use rag: { files } in neurolink.generate() or neurolink.stream(), it transparently leverages embed() and embedMany() under the hood to build context for your AI model.

import { NeuroLink } from "@juspay/neurolink";

const neurolink = new NeuroLink();

// NeuroLink automatically handles embedding and retrieval for RAG
const result = await neurolink.generate({
  input: { text: "What are the benefits of event-driven AI?" },
  rag: {
    files: ["./my-event-driven-ai-guide.md", "./middleware-patterns.pdf"], // Your documents
    chunkSize: 512,
    topK: 3,
  },
});

console.log(result.text); // AI response informed by semantic search of your files

For advanced use cases requiring more control over the embedding and retrieval steps, NeuroLink allows you to use createVectorQueryTool with explicit embed() calls and your chosen vector store.

Conclusion

Semantic search is a game-changer for building intelligent applications, moving beyond keyword matching to true understanding. NeuroLink, with its powerful embed() and embedMany() methods, makes it incredibly simple to integrate embedding generation into your TypeScript projects. Whether you're building a sophisticated RAG pipeline or a standalone semantic search engine, NeuroLink provides the tools to unlock the full potential of vector search. By leveraging these capabilities, you can build AI applications that are not just smart, but truly intuitive and responsive to user intent.

NeuroLink — The Universal AI SDK for TypeScript

GitHub: github.com/juspay/neurolink
Install: npm install @juspay/neurolink
Docs: docs.neurolink.ink
Blog: blog.neurolink.ink — 150+ technical articles