mcpns — NeuralSeek MCP Server + TypeScript SDK

Connect any MCP-compatible AI (Claude Desktop, VS Code Copilot, Cursor …) directly to your NeuralSeek instance. 15 tools out of the box: seek, run agents, upload/list/delete agents, stream, inspect logs, generate NTL from a description, replay run traces, and sync workspace.

MCP Server — Quick Setup

1. Install

npm install -g @osuna0102/mcp

No install required for VS Code / Claude Desktop — use npx (see step 3) and it downloads automatically on first use.

2. Configure your NeuralSeek instance

Create a .neuralseekrc.json in your home folder (or project root, or pass env vars):

{
  "instance": "Your_Instance_Name",
  "apiKey":   "xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx",
  "baseUrl":  "https://stagingapi.neuralseek.com/v1"
}

Or set environment variables instead (preferred for CI/Docker):

NS_INSTANCE, NS_API_KEY, NS_BASE_URL

All tools work with just instance and apiKey.

3. Add to VS Code (.vscode/mcp.json)

{
  "servers": {
    "neuralseek": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@osuna0102/mcp"]
    }
  }
}

Using npx means no global install needed — works on any machine with Node.js. The package is cached after the first run.

4. Add to Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "neuralseek": {
      "command": "npx",
      "args": ["-y", "@osuna0102/mcp"]
    }
  }
}

If you prefer using the globally-installed binary directly, run npm install -g @osuna0102/mcp first and then use "command": "mcpns" instead.

Restart Claude Desktop — 14 NeuralSeek tools will appear immediately.

5. Docker / environment-variable-only

docker run --rm -i \
  -e NS_INSTANCE="Your_Instance_Name" \
  -e NS_API_KEY="your-api-key" \
  -e NS_BASE_URL="https://stagingapi.neuralseek.com/v1" \
  node:22-alpine sh -c "npm install -g @osuna0102/mcp && mcpns"

Or point the config at the Docker binary:

{
  "mcpServers": {
    "neuralseek": {
      "command": "docker",
      "args": ["run","--rm","-i","-e","NS_INSTANCE=...","-e","NS_API_KEY=...","mcpns-image"]
    }
  }
}

Available MCP Tools

| Tool | Description | |------|-----------| | seek | RAG question-answering with confidence score and optional sources | | run_agent | Run a local .ntl agent file with params | | run_agent_stream | Same via SSE streaming — better for long-running agents | | upload_agent | Save a local .ntl to your NeuralSeek instance | | list_agents | List saved agents (name + description) | | list_agents_full | List all agents with full NTL source + metadata | | get_agent | Fetch one agent by name with its NTL source | | call_agent | Run a saved agent by name with params | | delete_agent | Delete one or more agents by name | | get_logs | Retrieve recent mAIstro run logs with run IDs for replay | | replay_run | Replay a run by ID — full step-by-step execution trace for debugging | | sync_agents | Pull all instance agents to workspace (auto-runs on startup) | | create_agent | Write a new NTL agent file to agents/custom/ | | generate_ntl | Generate a NTL draft from a plain-English description via makeNTL API | | backup_instance | Export full instance config to a .nsconfig file |

All tools require only an apiKey. The full NTL syntax reference is available as the ntl://reference MCP Resource (read-on-demand, not a tool).

Agent Development Workflow

When creating, testing, fixing, or touching any agent, always follow this cycle:

1. Find → list_agents / get_agent — retrieve current NTL from the instance
2. Edit → create_agent — write or update the local .ntl file in agents/custom/
3. Upload → upload_agent — save to the NeuralSeek instance (do NOT stream raw NTL inline as a test)
4. Run → call_agent — test the saved named agent on the instance
5. Verify output against user requirements. If not correct → repeat from step 1.

Read the ntl://reference MCP Resource before writing or editing NTL — it contains all 140+ nodes, params, and examples.

TypeScript SDK

The package also exports a fully-typed NeuralSeek SDK:

Installation

npm install @osuna0102/mcp

Quick Start

import { NeuralSeekClient } from '@osuna0102/mcp';

const client = new NeuralSeekClient({
  instanceId: process.env.NEURALSEEK_INSTANCE!,
  apiKey: process.env.NEURALSEEK_API_KEY!,
});

// Ask a question
const { answer, score } = await client.seek.seek({ question: 'What is NeuralSeek?' });

// Stream a response
for await (const chunk of client.seek.seekStream({ question: 'Explain mAIstro' })) {
  process.stdout.write(chunk.answer ?? '');
}

// Run a saved agent
const result = await client.maistro.run({
  agent: 'my-agent',
  params: [{ name: 'topic', value: 'loans' }],
});

// Upload an agent
await client.maistro.saveAgent({ name: 'my-agent', desc: '...', ntl: '...' });

Agent Definition (TypeScript-first, equivalent of IBM YAML agent)

import { AgentDefinition, NeuralSeekClient } from '@osuna0102/mcp';

const agent = new AgentDefinition({
  name: 'it-support-responder',
  description: 'Generate IT support responses',
  ntl: `[send to llm model="default"]
Handle this IT ticket:
Subject: $subject, Description: $description
[/send to llm]`,
  params: [
    { name: 'subject',     required: true },
    { name: 'description', required: true },
  ],
});

const { valid, errors } = agent.validate();
await client.maistro.saveAgent(agent.toSavedAgent());

Module Reference

| Module | Property | Key Methods | |---|---|---| | Seek | client.seek | seek(), seekStream(), rateAnswer() | | mAIstro | client.maistro | run(), runStream(), listAgents(), listAgentsFull(), saveAgent(), getAgent(), deleteAgents() | | Extract | client.extract | extractEntities(), categorize() | | Translate | client.translate | translate(), identify() | | Guardrails | client.guardrails | findPII(), semanticScore() | | Analytics | client.analytics | getAnalytics(), getLogs() | | Keys | client.keys | healthCheck(), validateKey(), runBatchTest() | | Curate | client.curate | listIntents(), createIntent(), importQA(), exportQA() | | Configure | client.configure | getSettings(), updateSettings(), listSecrets(), setSecret() |

CLI

neuralseek seek ask "What is NeuralSeek?"
neuralseek agent list
neuralseek agent deploy ./my-agent.agent.json
neuralseek agent run my-agent -p topic=loans
neuralseek logs list --limit 20
neuralseek health

Building from source

npm install
npm run build       # compile to dist/
npm run typecheck   # TypeScript check
npm test            # unit tests
npm run mcp:start   # run MCP server directly via tsx (no build)

Security

• Never commit .neuralseekrc.json with real credentials. It is already in .gitignore.
• Use NS_API_KEY / NEURALSEEK_API_KEY environment variables in CI/CD and Docker.