MCP Server

AVstackr exposes 258 tools via the Model Context Protocol — manage projects, products, customers, rooms, equipment, schematics, AI features, and external record storage from any MCP-compatible client.

Overview

AVstackr's MCP (Model Context Protocol) server gives AI tools direct access to your projects, products, customers, schematics, AI features, and external record storage — no REST API calls required. 258 tools are available covering the full project lifecycle.

Requirements

Connect with Claude Desktop (Recommended)

The fastest way to connect — no bridge script or API key needed. Claude Desktop connects directly via OAuth.

1. Open Claude Desktop and go to Settings
2. Navigate to Integrations
3. Click Add and paste: https://avstackr.com/mcp
4. Complete the OAuth login — you'll be redirected to AVstackr to authorize
5. All 258 tools appear automatically

For a full walkthrough with video, see the Claude Desktop Setup guide.

Connect Other MCP Clients

For clients that don't support OAuth, authenticate with an API key passed as a Bearer token in the Authorization header.

Step 1: Create an API Key

Go to Settings → API Keys → Create API Key. Give it a name and copy the key. It starts with avs_ and won't be shown again.

Step 2: Install the Bridge Script (stdio clients only)

The bridge translates between stdio (stdin/stdout) and Streamable HTTP. Copy and save as ~/mcp-http-bridge.js. Requires Node.js v18+.

#!/usr/bin/env node

const http = require('http');
const https = require('https');
const readline = require('readline');

const MCP_URL = process.env.MCP_URL;
const MCP_AUTH = process.env.MCP_AUTH;
const MCP_INSECURE = process.env.MCP_INSECURE === '1';

const debug = (msg) => process.stderr.write(`[bridge] ${msg}\n`);

if (!MCP_URL) { debug('MCP_URL not set, exiting'); process.exit(1); }
debug(`Starting bridge to ${MCP_URL}`);

const url = new URL(MCP_URL);
const isHttps = url.protocol === 'https:';
const transport = isHttps ? https : http;
const defaultPort = isHttps ? 443 : 80;

let sessionId = null;
let getStreamReq = null;
let lastEventId = null;
let shuttingDown = false;
const BACKOFF_START_MS = 1000;
const BACKOFF_MAX_MS = 30000;
let backoffMs = BACKOFF_START_MS;

function buildCommonHeaders(extra = {}) {
  const h = { 'Accept': 'application/json, text/event-stream', ...extra };
  if (MCP_AUTH) h['Authorization'] = MCP_AUTH;
  if (sessionId) h['Mcp-Session-Id'] = sessionId;
  return h;
}

function buildRequestOptions(method, headers) {
  const opts = {
    hostname: url.hostname, port: url.port || defaultPort,
    path: url.pathname + url.search, method, headers
  };
  if (isHttps && MCP_INSECURE) opts.rejectUnauthorized = false;
  return opts;
}

function writeToStdout(json) { process.stdout.write(json + '\n'); }

function parseSseChunk(buffer) {
  const events = []; let leftover = buffer;
  while (true) {
    const b = leftover.indexOf('\n\n');
    if (b === -1) break;
    const raw = leftover.slice(0, b); leftover = leftover.slice(b + 2);
    let id = null; const dataLines = [];
    for (const line of raw.split('\n')) {
      if (line.startsWith('id:')) id = line.slice(3).trim();
      else if (line.startsWith('data:')) dataLines.push(line.slice(5).trim());
    }
    if (dataLines.length > 0) events.push({ id, data: dataLines.join('\n') });
  }
  return { events, leftover };
}

function emitSseEvent(ev) {
  if (ev.id) lastEventId = ev.id;
  if (!ev.data) return;
  try { JSON.parse(ev.data); writeToStdout(ev.data); }
  catch { debug(`Dropping non-JSON SSE data`); }
}

// --- Session recovery (exponential backoff, retries indefinitely) ---
let reinitializing = false;
let resetBackoffMs = BACKOFF_START_MS;

function resetSession() {
  if (reinitializing || shuttingDown) return;
  reinitializing = true;
  debug(`Session lost — will re-initialize in ${resetBackoffMs}ms`);
  sessionId = null; lastEventId = null; backoffMs = BACKOFF_START_MS;
  if (getStreamReq) { try { getStreamReq.destroy(); } catch {} getStreamReq = null; }
  setTimeout(() => {
    reinitializing = false;
    const initMsg = {
      method: 'initialize',
      params: { protocolVersion: '2025-11-25', capabilities: {},
                clientInfo: { name: 'mcp-http-bridge', version: '1.0.0' } },
      jsonrpc: '2.0', id: `reinit-${Date.now()}`
    };
    handleClientMessage(initMsg);
    resetBackoffMs = Math.min(resetBackoffMs * 2, BACKOFF_MAX_MS);
  }, resetBackoffMs);
}

function isSessionLost(statusCode, body) {
  if (statusCode === 404) return true;
  if (statusCode === 403 && body && body.includes('does not match')) return true;
  return false;
}

// --- GET SSE stream ---
function openGetStream() {
  if (shuttingDown || !sessionId || getStreamReq) return;
  const headers = buildCommonHeaders();
  if (lastEventId) headers['Last-Event-ID'] = lastEventId;
  const options = buildRequestOptions('GET', headers);

  const req = transport.request(options, (res) => {
    if (res.statusCode === 405) { getStreamReq = null; return; }
    if (res.statusCode === 404 || res.statusCode === 403) {
      res.resume(); getStreamReq = null; resetSession(); return;
    }
    if (res.statusCode !== 200) { res.resume(); scheduleReconnect(); return; }
    backoffMs = BACKOFF_START_MS;
    let buffer = '';
    res.on('data', (chunk) => {
      buffer += chunk.toString('utf8');
      const { events, leftover } = parseSseChunk(buffer);
      buffer = leftover;
      for (const ev of events) emitSseEvent(ev);
    });
    res.on('end', () => { getStreamReq = null; scheduleReconnect(); });
    res.on('error', () => { getStreamReq = null; scheduleReconnect(); });
  });
  req.on('error', () => { getStreamReq = null; scheduleReconnect(); });
  req.end(); getStreamReq = req;
}

function scheduleReconnect() {
  if (shuttingDown || !sessionId) return;
  setTimeout(() => { backoffMs = Math.min(backoffMs * 2, BACKOFF_MAX_MS); openGetStream(); }, backoffMs);
}

// --- POST handling ---
function handleClientMessage(request) {
  const isNotification = request.id === undefined;
  const postData = JSON.stringify(request);
  const headers = buildCommonHeaders({
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(postData)
  });
  const options = buildRequestOptions('POST', headers);

  const req = transport.request(options, (res) => {
    const returnedSession = res.headers['mcp-session-id'];
    if (returnedSession && !sessionId) {
      sessionId = returnedSession;
      resetBackoffMs = BACKOFF_START_MS;
      debug(`Captured session id: ${sessionId}`);
      openGetStream();
    }
    if (res.statusCode === 202) { res.resume(); return; }
    const ct = (res.headers['content-type'] || '').toLowerCase();
    if (ct.includes('text/event-stream')) {
      let buffer = '';
      res.on('data', (chunk) => {
        buffer += chunk.toString('utf8');
        const { events, leftover } = parseSseChunk(buffer);
        buffer = leftover;
        for (const ev of events) emitSseEvent(ev);
      });
    } else {
      let data = '';
      res.on('data', (chunk) => { data += chunk; });
      res.on('end', () => {
        if (!data.trim()) return;
        if (isSessionLost(res.statusCode, data)) { resetSession(); return; }
        try { JSON.parse(data); writeToStdout(data.trim()); } catch {}
      });
    }
  });
  req.on('error', (e) => {
    const detail = `${e.code || 'ERR'}: ${e.message || '(no message)'}`;
    if (!isNotification) writeToStdout(JSON.stringify({
      jsonrpc: '2.0', id: request.id, error: { code: -32000, message: detail }
    }));
  });
  req.write(postData); req.end();
}

// --- Session termination ---
function terminateSession(cb) {
  if (!sessionId) { cb && cb(); return; }
  const headers = buildCommonHeaders();
  const opts = buildRequestOptions('DELETE', headers);
  const req = transport.request(opts, (res) => { res.resume(); res.on('end', () => cb && cb()); });
  req.on('error', () => cb && cb()); req.end();
}

// --- stdin loop ---
const rl = readline.createInterface({ input: process.stdin, terminal: false });
rl.on('line', (line) => {
  try { handleClientMessage(JSON.parse(line)); } catch (e) { debug(`stdin parse error: ${e.message}`); }
});
rl.on('close', () => shutdown());

function shutdown() {
  if (shuttingDown) return; shuttingDown = true;
  if (getStreamReq) { try { getStreamReq.destroy(); } catch {} getStreamReq = null; }
  terminateSession(() => process.exit(0));
  setTimeout(() => process.exit(0), 2000).unref();
}
process.on('SIGTERM', () => shutdown());
process.on('SIGINT', () => shutdown());

The bridge requires Node.js (v18+). No npm install needed — it uses only built-in modules.

Step 3: Configure Your Client

Add the following to your MCP client config (example: claude_desktop_config.json):

{
    "mcpServers": {
        "avstackr": {
            "command": "node",
            "args": ["~/mcp-http-bridge.js"],
            "env": {
                "MCP_URL": "https://avstackr.com/mcp",
                "MCP_AUTH": "Bearer avs_YOUR_API_KEY_HERE"
            }
        }
    }
}

Replace avs_YOUR_API_KEY_HERE with your API key from Step 1.

Step 4: Restart Your Client

After saving the config, restart your MCP client. All 258 tools should appear.

Troubleshooting

Check the MCP log at ~/Library/Logs/Claude/mcp*.log (macOS) for errors.

Available Tools

Once connected, your MCP client will see the following tools:

TOOL search_knowledge_base

Search manufacturer documentation using natural language. Returns articles ranked by relevance using vector similarity.

Example Response

{
    "count": 3,
    "results": [
        {
            "id": 42,
            "title": "TesiraFORTE Network Configuration",
            "summary": "Step-by-step guide for configuring network settings...",
            "content_snippet": "The TesiraFORTE connects via Dante...",
            "similarity": 0.891,
            "source_url": "https://support.biamp.com/...",
            "category": "network",
            "product_line": "tesira",
            "manufacturer_name": "Biamp"
        }
    ]
}

TOOL get_knowledge_base_entry

Get the full content of a knowledge base article by ID. Use this after searching to retrieve the complete article text.

Example Response

{
    "id": 42,
    "title": "TesiraFORTE Network Configuration",
    "summary": "Step-by-step guide for configuring network settings...",
    "content": "Full article text with configuration details...",
    "source_url": "https://support.biamp.com/...",
    "category": "network",
    "product_line": "tesira",
    "tags": ["dante", "networking", "configuration"],
    "manufacturer": "Biamp"
}

TOOL list_knowledge_base_manufacturers

List all available manufacturer knowledge bases. Use this to discover which manufacturers have documentation before searching.

Parameters: None

Example Response

{
    "count": 2,
    "manufacturers": [
        {
            "slug": "biamp",
            "display_name": "Biamp",
            "description": "Tesira, Devio, Parle, Vocia product families",
            "article_count": 1292
        },
        {
            "slug": "crestron",
            "display_name": "Crestron",
            "description": "Control systems, SIMPL programming, hardware",
            "article_count": 3533
        }
    ]
}

Typical Workflow

1. Call list_knowledge_base_manufacturers to see available knowledge bases
2. Call search_knowledge_base with a natural language question and optional manufacturer filter
3. Call get_knowledge_base_entry with an article ID to get the full content

Error Responses

TOOL get_schematic

Get the project's signal-flow schematic as a shareable viewer URL. Returns a 30-day signed link that renders the saved schematic as a PDF in any browser, with the title block exactly as the user configured it (status, revisions, drawn-by, project number, notes — everything). Use when the caller asks to see, share, or download a project's schematic. Each project has at most one schematic; this tool resolves it from the project id.

Example Response

{
    "success": true,
    "project_id": 431,
    "schematic_id": 51,
    "page_count": 1,
    "device_count": 12,
    "has_layout": true,
    "view_url": "https://app.avstackr.com/schematic/eyJ...",
    "message": "Schematic retrieved — open view_url in a browser to view or download as PDF."
}

When the project has no saved schematic, the response is { "error": "No schematic found for project ..." }.

TOOL get_schematic_image

Render the project's signal-flow schematic to PNG(s) — the same canvas the browser editor draws, captured server-side — so an AI agent can visually verify a layout it built (spot out-of-bounds bundles, check spacing, read device labels) instead of reasoning from JSON alone. Every response includes a text block with a 30-day signed viewer link (open the full zoomable drawing in a browser — share this with a human). Page defaults to 1 and is capped to the schematic's real page count.

Three modes trade coverage for detail:

• Overview (default) — the whole page as one image, roughly 44 pixels per drawing inch. Best for gross layout, out-of-bounds bundles, and spacing.
• Region zoom — pass all four region_x, region_y, region_width, region_height (page inches, top-left origin over the 36×24 sheet) to spend the pixel budget on one rectangle. Smaller regions win: an 8×6-inch corner reaches about 173 px/in (roughly 4× the overview), an 18×12-inch half-sheet about 83 px/in. Use it to read labels and wire numbers the overview can't resolve. Returns 1 text block + 1 image.
• Tiled sweep — pass tiled: true to render a 3×2 overlapping grid at about 101 px/in (roughly 2.3× the overview). The response leads with a geometry-index text block (per-tile page-inch bounds, so any observation maps back to sheet inches), then alternates TILE n text and image blocks for the 6 tiles. A sweep costs about 16.5k visual tokens, so reach for it deliberately — end-of-work verification, not every iteration.

Give all four region params or none — a partial region, or a region combined with tiled: true, returns an explanatory text block instead of an image. When the project has no saved schematic, the tool returns a single text block: No schematic found for project ....

TOOL get_project_excel_url

Mint a 7-day signed URL to download the project's Excel workbook (.xlsx). Use when the caller asks to download, send, or share a project's Excel export. All formatting options are optional — omit any to fall back to the project's saved default, then the system default.

Example Response

{
    "success": true,
    "project_id": 42,
    "url": "https://yourdomain.com/project-excel/<token>?mode=FullProject",
    "expires_at": "2026-05-26T14:32:08Z",
    "filename": "Acme HQ - 2026-05-19.xlsx",
    "message": "Excel export URL minted — open url in a browser to download the .xlsx file. Link expires in 7 days."
}

For the user-workflow guide (what the workbook contains, how saved defaults work), see Excel Export. For the equivalent REST API endpoint with the full PascalCase parameter table, see Projects API.

Available Tools

All tools require authentication (OAuth or API key) and an active subscription.

Projects

Rooms & Equipment

Products

Custom Device Blocks

A custom device block is imported artwork that draws in place of a schematic device's standard rectangle — the footprint and ports stay the standard block's, only the picture changes. Agents import artwork by sending a PNG or PDF base64-encoded in content_base64, at most 1.5 MB once decoded (the in-app library at Schematics → Custom Blocks takes up to 50 MB for larger sources). The format is read from the file's own bytes, never its name, so send the original file unmodified. Artwork is auto-cropped to its visible content and, by default, thresholded to black strokes on transparency so it tints white on the dark canvas and prints as-is on white paper.

Customers

AI Features

Knowledge Base

Ops Intelligence

Memory

Skills

Skills are saved step-by-step procedures agents load and follow — memory stores facts, skills store how work gets done. Each skill carries a trigger description saying when to use it; when a request matches, the agent reads the skill and follows its steps. Skills are yours (scope private) or your company's (scope shared), and you can browse or edit them under Skills in the app.

External Record Store

Five tools for storing and retrieving opaque JSON records under tenant-scoped namespaces. For an overview of what it does and how to set it up, see External Record Store. For parameter tables and example responses, see the External Record Store API. Manage the namespace registry under Global Project Configuration → External Records.