MCP Server

AVstackr exposes 319 tools via the Model Context Protocol — manage projects, products, customers, rooms, equipment, schematics, AI features, and external record storage from an MCP client that signs in with OAuth, such as Claude Desktop or claude.ai.

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. 319 tools covering the full project lifecycle are available to a client that signs in with OAuth. A client that connects with an API key reaches the two knowledge base tools.

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 319 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. An API key connects to https://avstackr.com/mcp/kb. This endpoint offers the two knowledge base tools, search_knowledge_base and list_knowledge_base_manufacturers. The full tool set needs the OAuth login on https://avstackr.com/mcp, described above.

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/kb",
                "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. The two knowledge base tools, search_knowledge_base and list_knowledge_base_manufacturers, 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 one manufacturer's documentation for a question. The tool returns the passages that match, best match first, each with its article id, title, source URL and text. Each article's text is divided into passages of at most 400 words. A short article is a single passage, so the search returns its whole text.

A search costs 1 credit. A search is charged whenever passages come back, and it has no relevance cut-off, so a search of a manufacturer that has documentation returns passages and is charged nearly every time. A search that returns no passage, names an unknown manufacturer or fails is not charged. The credit balance is checked before the search runs, and a team member with read-only access is refused before any search.

The passages of one response hold at most 3,000 words in total, so a response can hold fewer passages than limit.

Example Response

{
    "count": 1,
    "credits_charged": 1,
    "results": [
        {
            "article_id": 42,
            "title": "TesiraFORTE Network Configuration",
            "manufacturer_name": "Biamp",
            "manufacturer_slug": "biamp",
            "product_line": "tesira",
            "source_url": "https://support.biamp.com/...",
            "text": "The TesiraFORTE connects via Dante...",
            "score": 0.891,
            "match": "hybrid"
        }
    ]
}

score is the reranker's relevance score for the passage, rounded to three decimal places, and null when the reranker did not score it. match says how the search found the passage: semantic (by meaning), keyword (by matching words) or hybrid (both). product_line and source_url are null when the article has none. A search that finds no passage returns "count": 0, "credits_charged": 0 and an empty results array.

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 and their slugs
2. Call search_knowledge_base with a natural language question and the manufacturer's slug. The passages it returns are the documentation text to answer from

Error Responses

None of the search_knowledge_base errors above is charged.

The tools below need the OAuth login on https://avstackr.com/mcp.

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. The OAuth login on https://avstackr.com/mcp reaches every tool and needs an active plan or a live free trial. An API key on https://avstackr.com/mcp/kb reaches the two tools in the Knowledge Base table and needs a paid plan.

Projects

Rooms & Equipment

Floor Plans

Products

Device Tags

Every physical unit on a project can carry a device tag such as DISP-003, built from the company's tag pattern out of the product's device category and the line's system. See Device Tags. Every tool below that changes data returns READ_ONLY_ACCESS for a Read-only user in Claude Desktop and in AVIP Assistant, and saves nothing. A voice agent linked to a Read-only user refuses earlier, with its "not enabled for this agent" message, and also saves nothing. AVIP Assistant, the in-app copilot, has the same tools with the same arguments.

The line item attribute key tools carry each key's CAD attribute tag, the AutoCAD block attribute it maps to: list_line_item_attribute_keys returns cad_attribute_tag on each key, and create_line_item_attribute_key and rename_line_item_attribute_key take an optional cad_attribute_tag (on rename, an empty string clears it). They carry how the key syncs with drawings too: each key returns cad_sync, which is push, pull, both, or none for a key without a tag, and the create and rename tools take an optional cad_sync of push, pull or both, set after the tag. A key given a tag without one syncs push. Any other word returns INVALID_INPUT before anything is saved; cad_sync on a key left without a tag returns INVALID_SYNC_DIRECTION, and create then does not keep the key while rename keeps the new name and tag.

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

Vendors

No tool sets a vendor's API addresses or credentials. Enter them with Configure API on the Vendors page. A ReadOnly user can read a vendor's API integration status but cannot test, switch or clear it.

Configuration

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), your company's (scope shared), or the platform's (scope platform, maintained by AVstackr and read-only), 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.