Cognipeer Console SDK MCP server
Commit Nov 3, 2026Provides a TypeScript/JavaScript client to interact with chat, agents, embeddings, vector databases, and browser automation via the Cognipeer Console.
Also known as Cognipeer/console-sdk
- Stars
- 7
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 3, 2026
- License
- MIT
What is Cognipeer Console SDK MCP?
Cognipeer Console SDK provides a TypeScript/JavaScript client to interact with chat, agents, embeddings, vector databases, and browser automation via the Cognipeer Console.
Summary generated from the project's README
About Cognipeer Console SDK MCP server
Developers building AI-driven applications can use this TypeScript and JavaScript SDK to integrate the Cognipeer Console into their workflows. It provides a single typed client to manage a wide range of AI tasks, including chat completions, embeddings, and vector database operations. The SDK is designed for both Node.js and browser environments, supporting modern ESM and CommonJS formats.
Users can orchestrate complex agent behaviors by invoking managed agents, scheduling asynchronous jobs, or setting up automated triggers via webhooks and cron schedules. The client also handles specialized tasks like browser automation, web crawling, and document processing through OCR and markdown conversion. To ensure security and control, the SDK includes tools for content moderation via guardrails, cost reporting, and enforced spend caps per tenant or model. Integration requires an API key and an optional base URL for custom console deployments.
What you can do with it
- 1Automate agentic workflowsYou can schedule agents to run on a cron schedule or trigger them using webhooks.
- 2Manage semantic memoryDevelopers can persist and recall scoped memories using vector providers and embedding models.
- 3Control AI spendingThe SDK allows for monitoring costs and setting strict budget limits for different users or models.
- 4Automate web interactionsYou can drive live browser sessions or record and replay tasks as automated flows.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecognipeer/console-sdk is public and reachablegithub.com/cognipeer/console-sdk ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-03github.com/cognipeer/console-sdk ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubCognipeer Console SDK
Official TypeScript/JavaScript SDK for Cognipeer Console: call chat, agents, embeddings, vectors, RAG, MCP, guardrails and tracing through one typed client.
Docs · Quick start · Examples · Changelog · Contact
Features
- 🤖 Chat Completions - OpenAI-compatible chat API with streaming support
- 📦 Batch API - OpenAI-compatible asynchronous bulk inference (chat + embeddings)
- 🚦 Moderations - OpenAI-compatible content moderation backed by guardrails
- 💰 Spend & Budgets - Cost reporting and enforced spend caps per tenant/token/model
- 🎧 Realtime - Low-latency voice sessions over WebSocket (binary PCM/G.711 audio, server turn detection, barge-in, first message, latency metrics) and Twilio phone calls
- 🧑✈️ Agents - Invoke Console-managed agents (OpenAI Responses API, streaming), run async/scheduled/deferred jobs (
agents.runs), and triggers that start an agent on their own (agents.triggers: schedule, once, manual, webhook; an agent can have several) - 📊 Embeddings - Text vectorization for semantic search
- 🗄️ Vector Operations - Manage vector databases (Pinecone, Chroma, Qdrant, etc.)
- 📁 File Management - Upload, download, and manage files with markdown conversion + file providers
- 🎙️ Audio - OpenAI-compatible STT, translation, and TTS
- 📄 OCR - Document text extraction with layout/table/KV features
- 🕸️ Crawler - Scheduled and ad-hoc web crawling jobs
- ⚙️ Automations - Trigger and pause built-in scheduled jobs
- 🔀 Rerankers - Cohere-compatible reranking
- 🛰️ MCP - Talk to the built-in Console MCP server and tenant-configured MCP servers
- 🌐 Browser Automation - Manage browser profiles, drive live sessions, record a task once and replay it as a flow, and call browsers published as MCP servers
- 🔍 Agent Tracing - Streaming + bulk ingest, OTLP/HTTP JSON, plus OpenTelemetry exporter
- 🧠 Memory Stores - Persist, search, and recall scoped memories
- 🛡️ Guardrails - Evaluate content with tenant guardrail policies
- 🔒 Type-Safe - Full TypeScript support with comprehensive types
- ⚡ Modern - ESM and CommonJS support, works in Node.js and browsers
Installation
npm install @cognipeer/console-sdk
yarn add @cognipeer/console-sdk
pnpm add @cognipeer/console-sdk
Quick Start
import { ConsoleClient } from '@cognipeer/console-sdk';
// Initialize the client
const client = new ConsoleClient({
apiKey: 'your-api-key',
baseURL: 'https://your-console.example.com', // Optional, defaults to https://console.cognipeer.com
});
// Chat completion
const response = await client.chat.completions.create({
model: 'gpt-4',
messages: [
{ role: 'system', content: 'You are a helpful assistant.' },
{ role: 'user', content: 'Hello!' },
],
});
console.log(response.choices[0].message.content);
// Streaming chat
const stream = await client.chat.completions.create({
model: 'gpt-4',
messages: [{ role: 'user', content: 'Tell me a story' }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content || '');
}
// Create embeddings
const embeddings = await client.embeddings.create({
model: 'text-embedding-3-small',
input: 'Hello, world!',
});
console.log(embeddings.data[0].embedding);
// Vector operations
await client.vectors.upsert('my-provider', 'my-index', {
vectors: [
{
id: 'vec1',
values: [0.1, 0.2, 0.3],
metadata: { text: 'Hello world' },
},
],
});
const results = await client.vectors.query('my-provider', 'my-index', {
query: {
vector: [0.1, 0.2, 0.3],
topK: 5,
},
});
// File upload
const file = await client.files.upload('my-bucket', {
fileName: 'document.pdf',
data: 'data:application/pdf;base64,JVBERi0xLjQK...',
convertToMarkdown: true,
});
// Memory
const store = await client.memory.stores.create({
name: 'Support Memory',
vectorProviderKey: 'pinecone-main',
embeddingModelKey: 'text-embedding-3-small',
});
await client.memory.add(store.key, {
content: 'User prefers concise billing explanations.',
scope: 'user',
scopeId: 'user_123',
tags: ['billing', 'preferences'],
source: 'manual',
});
const recall = await client.memory.recall(store.key, {
query: 'user communication preferences',
scope: 'user',
scopeId: 'user_123',
});
console.log(recall.context);
Documentation
Full documentation is available at docs.cognipeer.com/console-sdk
If you need the platform itself, deployment guidance, tenant architecture, provider setup, or raw HTTP API semantics, use the Cognipeer Console docs.
- Getting Started
- Working with Console
- Console API Mapping
- Chat API
- Embeddings API
- Audio API
- OCR API
- Crawler API
- Automations API
- Rerankers API
- Web Search API
- MCP API
- Guardrails API
- Memory API
- Vector API
- Files API
- Tracing API
- Examples
API Reference
Client Configuration
const client = new ConsoleClient({
apiKey: string; // Required: Your API token
baseURL?: string; // Optional: API host root (default: https://console.cognipeer.com).
// Legacy URLs ending in /api/client/v1 are normalised automatically.
timeout?: number; // Optional: Request timeout in ms (default: 60000)
maxRetries?: number; // Optional: Max retry attempts (default: 3)
fetch?: typeof fetch; // Optional: Custom fetch implementation
});
Available Methods
Chat and models
client.chat.completions.create(params, { sessionId?, idempotencyKey?, signal? })- Create chat completion (streaming supported;response_format,stream_options.include_usage,service_tier,metadata;modelmay be an agent,agent:<key>)client.models.list()-dataholds the project's LLM models AND its active agents (id: 'agent:<key>',cognipeer.kind === 'agent'; useisAgentModelEntry);modelsthe registry rows (a token that can only read agents gets the agents alone:models: [], no providers)
Agents
client.agents.responses.create(params, options?)- Invoke an agent (OpenAI Responses API format). Runs the published version (version: 3pins,version: 'draft'runs the draft);text.formatstructured output (output_parsed),metadata,service_tier,variables;stream: truereturns an async iterator of typedresponse.*events; a turn past the Console's window answers202and returns the response withstatus: 'queued' | 'in_progress'(never throws)client.agents.responses.retrieve(id)/.cancel(id)- Read a response (resp_<runId>) / stop its run (POST /responses/{id}/cancel)client.agents.runs.create(agentKey, body, { idempotencyKey?, prefer?, signal? })- Start a run (wait,class: 'deferred',run_at/delay_seconds,variables,response_format,callback,metadata,stream); anIdempotency-Keyis generated when you pass none (also withstream: true)client.agents.runs.list(query)- Await it for a page (data,has_more,last_id,getNextPage()) orfor awaitevery run; filtersagent,status,class,session_id,trigger_id,channel,trigger,metadata,created_after/beforeclient.agents.runs.get(runId, { wait? })/.cancel(runId)/.queue()- Run status (optionally long-polled) withresult,output_text,output_parsed,error; cancel; running/queued/scheduled counters per classclient.agents.runs.wait(runId, { timeoutMs?, waitSeconds?, signal? })- Uses the?wait=long-poll until the run is terminal orrequires_action(waiting on an approval/question)client.agents.runs.events(runId, { after? })/.events.stream(runId)- The run's session events (JSON, SSE withLast-Event-IDresume)client.agents.triggers.list/create/get/update/delete(agentKey, …)- Triggers: start an agent with a prompt on a cron schedule (+ IANA timezone), once, by hand, or when an authenticated webhook delivery arrives; an agent can have several, each has onetype; each fire is a runclient.agents.triggers.run(agentKey, triggerId, { variables?, metadata?, payload?, headers?, dry_run? }, { wait?, prefer?, idempotencyKey?, signal? })- Fire a trigger now (200run, or202while it goes); on a webhook triggerpayload/headersare a sample event anddry_run: trueonly shows the turn it would buildclient.agents.triggers.rotateWebhookSecret(agentKey, triggerId, { grace_seconds?, secret? })/.deliveries(agentKey, triggerId, { before?, limit? })- Replace a webhook trigger's secret (the old one keeps working forgrace_seconds); its delivery logsignTriggerWebhook(secret, body, { timestamp?, eventId?, event? })- The headers that authenticate a delivery to a webhook trigger with authsignatureclient.agents.sessions.create({ agent, title?, metadata?, budget? })- Start an empty session (nothing runs); continue it withresponses.create({ session_id })client.agents.sessions.list({ agent?, status?, limit?, after? })- Await it for a page, orfor awaitit for every session (newest first)client.agents.sessions.delete(conversationId)- Delete a session with its files, events and open actionsclient.agents.sessions.cancel(conversationId)- Stop the turn running on a session ({ object: 'agent.session.cancel', session_id, cancelled, run_ids })client.agents.sessions.get(conversationId)- Runtime state:runtime_status,stop_reason,pending_actions,last_event_seqclient.agents.sessions.actions.list(conversationId)/.resolve(conversationId, actionId, body, { background? })- Pending approvals/questions (read from the session; the Console has no client list route) and answering themclient.agents.sessions.events.list(conversationId, { after?, types?, limit? })/.stream(conversationId, { after?, types?, signal? })- The session event log: paged, or followed live with automaticLast-Event-IDreconnectclient.agents.sessions.reminders.list(conversationId, { status? })/.cancel(conversationId, reminderId)- Messages the agent scheduled to come back to (status:active= scheduled only, default, orall); cancel a scheduled one (404 unknown, 409 already fired). A reminder is a run with channelreminder; its session events carryorigin: 'reminder'/trigger: 'reminder'client.agents.sessions.update(conversationId, { budget, resume })- Raise, set or remove (null) the session spend budget (budgetis required;{ max_cost_usd, on_reach })client.agents.sessions.files.upload/list/delete(conversationId, …)- Files the agent can read in the conversation; each file says where it is stored (bucket_key,path)client.agents.sessions.files.content(conversationId, fileId, { variant? })/.contentStream(…)- Download a session file (the original, or themarkdowntext the agent reads)client.agents.get(key).attachments- Whether the agent takes files now, its limits, whether its model reads images, andoutputs(files it writes for the person)client.webhooks.create/list/get/update/delete/rotateSecret/test/deliveries/redeliver/eventTypes- Webhook subscriptions (objects keep camelCase field names, unlike the agent API's snake_case)verifyWebhook({ rawBody, signatureHeader, secret })from@cognipeer/console-sdk/webhooks(Node.js) - Verify a signed webhook delivery (verifyAgentRunCallbackis the same check, kept for existing code)
// Chat-style call, structured output, streaming
const res = await client.agents.responses.create({ model: 'support-bot', input: 'Hi' });
console.log(res.status, res.output_text);
for await (const event of await client.agents.responses.create({ model: 'support-bot', input: 'Hi', stream: true })) {
if (event.type === 'response.output_text.delta') process.stdout.write(event.delta);
}
// A job: queued, scheduled or deferred; wait for it with the long-poll
const run = await client.agents.runs.create(
'research-agent',
{ input: 'Compare these vendors', class: 'deferred', metadata: { ticket: 'OPS-12' } },
{ idempotencyKey: 'job-42' },
);
const done = await client.agents.runs.wait(run.id, { timeoutMs: 15 * 60_000 });
if (done.status === 'succeeded') console.log(done.output_text, done.output_parsed);
// A trigger that starts the agent on a schedule
await client.agents.triggers.create('report-bot', {
name: 'Weekday digest',
type: 'schedule',
schedule: { cron: '0 9 * * 1-5', timezone: 'Europe/Istanbul' },
prompt: 'Summarise yesterday',
});
// ...and another on a webhook: post events to trigger.webhook.url (the secret is shown once)
const trigger = await client.agents.triggers.create('report-bot', {
name: 'On deploy',
type: 'webhook',
webhook: { preset: 'generic', events: ['deploy.finished'] },
prompt: 'Summarise the deploy of {{payload.service}}',
});
if (trigger.type === 'webhook') console.log(trigger.webhook.url, trigger.webhook.secret);
See Agents for runs, triggers, variables, 202 handling, structured output and error codes.
Variables
An agent can declare variables: named, typed values (text, number, integer, yes/no, JSON; required or optional, with
allowed values and a default) that a caller sends next to the message. The Console checks them before the model is called
(a missing required value or a wrong type is a 400 invalid_variables, and nothing is spent). The agent's instructions can use
them as {{variables.<name>}}, and they are also added to the user message as a Variables JSON block, so the model sees
them even when the instructions do not mention them. agents.get(key).variables_schema publishes them as a JSON Schema, so
n8n, CI scripts, other agents and forms know what to send.
They are best for calls a program or an automation makes: the runs API, triggers (a schedule with fixed values, a webhook that maps payload fields into them), n8n or CI pipelines, an agent that another agent calls as a tool.
const agent = await client.agents.get('report-bot');
agent.variables_schema; // JSON Schema of the variables; null when the agent declares none
await client.agents.runs.create('report-bot', {
input: 'Weekly numbers', // the message
variables: { team: 'ops', region: 'EMEA' }, // the variables, next to it
});
Chat is different. Chat clients (Open WebUI, other OpenAI-compatible apps, the portal chat UI) send only the person's text and
never fill variables, so a required variable without a default makes every chat message fail with 400 invalid_variables.
For an agent that is also used in chat, keep its variables optional or give each one a default. Values belong to the turn that
sends them: send them again on a follow-up turn of the same session (the Variables block of each turn stays in that turn's
message in the history).
Approvals and questions (human in the loop)
An agent can pause a turn to ask for a tool approval or to ask the user a question. The turn then
comes back with status: 'requires_action' (Responses API) or a run in requires_action, listing
what to answer. Answer with sessions.actions.resolve(); the turn continues from where it stopped.
const res = await client.agents.responses.create({ model: 'ops-agent', input: 'Clean up staging' });
if (res.status === 'requires_action') {
const conversationId = res.conversation!.id; // also res.cognipeer.session_id
for (const action of res.required_action!.actions) {
if (action.kind === 'tool_approval') {
console.log('Agent wants to run', action.tool_name, action.args);
// `approved_args` replaces the arguments; `remember_for_session` stops asking for this tool.
const next = await client.agents.sessions.actions.resolve(conversationId, action.id, {
decision: 'allow',
remember_for_session: true,
});
// `next` is the continuation (Responses shape). While other actions of the same pause are
// still open it is a bare `requires_action` body (empty `output`, no `usage`).
} else {
await client.agents.sessions.actions.resolve(conversationId, action.id, {
answers: { [action.questions![0].question]: 'staging' }, // or { cancelled: true } to skip
});
}
}
}
resolve(..., { background: true })queues the continuation and returns anAgentRun(202).- For a background run,
runs.wait()returns when the run isrequires_action; readrun.result.required_action.actionsandrun.stop_reason. Theagent_run.requires_actioncallback/webhook event fires at the same moment. - Errors (
CognipeerAPIError):403 action_forbidden(not an allowed approver),404action_not_found,409 action_not_pending(answered by someone else),409 action_cancelled(withdrawn before it was answered),410 action_expired,400 invalid_resolution,503 authorization_unavailable(the Console could not decide; nothing changed, retry). Test withisAgentActionErrorCode(error, AgentActionErrorCodes.Expired). - A new user message while an action is pending is rejected with
409 pending_action(AgentActionErrorCodes.PendingAction, ids inerror.response.error.pending_action_ids) unless the agent is configured to cancel pending requests.
Session events and live follow
Every session has an append-only event log (user.message, agent.tool_use, agent.tool_result,
action.required, action.resolved, agent.message, session.status_idle, session.work_done,
session.error, ...). Read it with events.list() or follow it:
import { isSessionEvent } from '@cognipeer/console-sdk';
const session = await client.agents.sessions.get(conversationId);
const controller = new AbortController();
for await (const event of client.agents.sessions.events.stream(conversationId, {
after: session.last_event_seq, // omit to replay the whole log first
signal: controller.signal,
})) {
if (event.type === 'agent.message.delta') process.stdout.write(event.data.text); // live only
if (isSessionEvent(event, 'action.required')) notifyApprover(event.data.action_id);
if (isSessionEvent(event, 'session.status_idle')) break; // the stream itself never ends on idle
}
stream() reconnects by itself (network drop, idle stall, the server's hourly cap) using
Last-Event-ID, never repeats or skips a persisted event, gives up after maxReconnects (default 8)
silent attempts, and throws the abort reason when signal aborts. agent.message.delta text chunks
are live-only (they have no seq and are not replayed); the full text is in agent.message.
Event data keys are snake_case (tool_call_id, action_id, stop_reason, ...); tool args and
question answers are passed through untouched. Unknown event types arrive as plain { type, data }
objects: ignore them.
Sessions: start, list, delete
// Start a session without a message (nothing runs, nothing is spent), then continue it by id.
const session = await client.agents.sessions.create({
agent: 'support-bot',
metadata: { ticket: 'T-1042' }, // up to 16 string pairs, returned as session.metadata
});
const reply = await client.agents.responses.create({
model: 'support-bot',
session_id: session.id, // or `conversation: session.id` / `conversation: { id }` (OpenAI style)
input: 'I have a billing question',
});
// One page (newest first)...
const page = await client.agents.sessions.list({ agent: 'support-bot', status: 'requires_action', limit: 50 });
console.log(page.data.map((s) => `${s.id} ${s.runtime_status} ${s.message_count} messages`));
const next = await page.getNextPage(); // null on the last page
// ...or every session, fetching pages as you go.
for await (const s of client.agents.sessions.list({ agent: 'support-bot' })) console.log(s.id, s.title);
await client.agents.sessions.delete(session.id); // with its files, events and open actions
session_id, conversation and previous_response_id name the same conversation: give one, or
several that agree (400 session_conflict when session_id / conversation and
previous_response_id name different sessions, 400 invalid_request when session_id and
conversation disagree; 404 session_not_found for another agent's or project's session). delete() is refused with 409 agent_run_conflict while a run is active.
Details and the error table: Agents → Sessions.
Stopping a turn
// By session (`res.cognipeer.session_id`, `res.conversation.id`, `run.session_id`)...
const { cancelled, run_ids } = await client.agents.sessions.cancel(sessionId);
// ...or by response id (`resp_<runId>`): answers the response (`cancelled`, or `in_progress` while it lands).
await client.agents.responses.cancel(response.id);
Cancellation is cooperative: the turn ends at its next checkpoint, keeping what it had streamed (a
streamed Response ends with response.incomplete). cancelled: false means nothing was running; an
unknown id is a 404. This is how an inline call (responses.create, chat completions, A2A) is stopped
from a second request. Closing the connection (signal) alone does not stop a server-side turn, except
a responses.create({ stream: true }) without background: true. agents.runs.cancel(runId) stops one run.
Cognipeer Console SDK MCP questions
Can I use this SDK for browser automation?
Yes, you can manage browser profiles, drive live sessions, and call browsers published as MCP servers.
Does the SDK support vector databases?
Yes, it allows you to manage vector databases such as Pinecone, Chroma, and Qdrant.
How do I install the SDK?
You can install it using npm, yarn, or pnpm.