PulseLink MCP

CLI or API | MCP

Version: 2.3.0

Documentation — Installation, deployment, usage across the API, CLI, and MCP backing platform are maintained in the official documentation.

---

Overview

PulseLink MCP Server

PulseLink — keyless open-web & social research source (MCP Server)

This repository is actively maintained - Contributions are welcome!

MCP

MCP Configuration Examples

Install the connector-focused [mcp] extra. Examples use pulselink-mcp[mcp] to add FastMCP / FastAPI through agent-connector-sdk; the required Agent Connector SDK core still carries epistemic-graph[full]. The [agent-runtime] extra additionally enables model orchestration.

stdio Transport (local IDEs — Cursor, Claude Desktop, VS Code)

{
  "mcpServers": {
    "pulselink-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "pulselink-mcp[mcp]",
        "pulselink-mcp"
      ],
      "env": {
        "MCP_TOOL_MODE": "intent",
        "PULSETOOL": "True"
      }
    }
  }
}

Runtime references require an alias-aware launcher such as Arbora. Other launchers must omit those entries and inject the resolved values through their own runtime secret boundary.

Streamable-HTTP Transport (networked / production)

{
  "mcpServers": {
    "pulselink-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "pulselink-mcp[mcp]",
        "pulselink-mcp",
        "--transport",
        "streamable-http",
        "--port",
        "8000"
      ],
      "env": {
        "TRANSPORT": "streamable-http",
        "HOST": "127.0.0.1",
        "PORT": "8000",
        "MCP_TOOL_MODE": "intent",
        "PULSETOOL": "True"
      }
    }
  }
}

Alternatively, connect to a pre-deployed Streamable-HTTP instance by url:

{
  "mcpServers": {
    "pulselink-mcp": {
      "url": "http://localhost:8000/pulselink-mcp/mcp"
    }
  }
}

Run a reviewed container image as a least-privilege stdio child (no listener or published port):

docker run -i --rm \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --pids-limit=256 \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
  -e TRANSPORT=stdio \
  -e MCP_TOOL_MODE=intent \
  -e PULSETOOL=True \
  registry.example.invalid/pulselink-mcp@sha256:<digest> pulselink-mcp

For containerized network HTTP, supply an authenticated TLS ingress (or direct server TLS), exact MCP_ALLOWED_HOSTS, and an exact trusted-proxy CIDR policy through the operator-owned deployment profile. The generator does not emit an unauthenticated non-loopback listener.

Auto-generated from the code-read env surface (MCP_TOOL_MODE + package vars) — do not edit.

Additional Deployment Options

pulselink-mcp can run as a local stdio process or container, or behind a remote network boundary. The Deployment guide carries the detailed transport contract.

• Local container — launch a reviewed immutable image as a least-privilege stdio child with no listener or published port.
• Remote URL — connect through an operator-supplied authenticated HTTPS ingress. Keep its URL, outbound identity references, trust profile, and exact MCP_ALLOWED_HOSTS in AgentConfig.

Available MCP Tools

This table is auto-generated from the live server — do not edit by hand.

Condensed action-routed tools (MCP_TOOL_MODE=condensed)

MCP Tool	Toggle Env Var	Description
pulse_fetch	PULSETOOL	Fetch one item (full text/body/transcript). CONCEPT:PK-OS.governance.search-fetch-list-transcribe
pulse_ingest	PULSETOOL	Search/list a source and natively ingest the results into epistemic-graph.
pulse_list	PULSETOOL	List items from a source channel/feed. CONCEPT:PK-OS.governance.search-fetch-list-transcribe
pulse_search	PULSETOOL	Search a source and return normalized documents. CONCEPT:PK-OS.governance.search-fetch-list-transcribe
pulse_status	PULSETOOL	Per-source backend + credential health (the doctor). CONCEPT:PK-OS.governance.search-fetch-list-transcribe
pulse_transcribe	PULSETOOL	Transcribe video/audio to text. CONCEPT:PK-OS.governance.audio-video-sources-transcript

Verbose 1:1 API-mapped tools (MCP_TOOL_MODE=verbose or both)

6 per-operation tools — one per public API method (click to expand)

MCP Tool	Toggle Env Var	Description
pulselink_fetch	PULSE_LINK_CLIENTTOOL	Invoke the fetch operation.
pulselink_list_items	PULSE_LINK_CLIENTTOOL	Invoke the list_items operation.
pulselink_search	PULSE_LINK_CLIENTTOOL	Invoke the search operation.
pulselink_sources	PULSE_LINK_CLIENTTOOL	Invoke the sources operation.
pulselink_status	PULSE_LINK_CLIENTTOOL	Invoke the status operation.
pulselink_transcribe	PULSE_LINK_CLIENTTOOL	Invoke the transcribe operation.

6 action-routed tool(s) · 6 verbose 1:1 tool(s). Each is enabled unless its <DOMAIN>TOOL toggle is set false; MCP_TOOL_MODE selects the surface (intent default — the six verb-tools, granular set loaded on demand · condensed action-routed · verbose 1:1 · both). Auto-generated — do not edit.

Environment Variables

Package environment variables

Variable	Example	Description
HOST	0.0.0.0
PORT	8000
TRANSPORT	stdio	options: stdio, streamable-http, sse
TLS_PROFILE	private-pki	TLS verification is mandatory. Select a named runtime profile from AgentConfig.
TLS_PROFILES_REF	secret://runtime/tls-profiles
PULSELINK_TLS_PROFILE	private-pki
PULSELINK_TLS_PROFILE_REF	secret://runtime/pulselink-tls-profile
MODEL_TLS_PROFILE	public-default
MODEL_TLS_PROFILE_REF	secret://runtime/model-tls-profile
PULSELINK_MCP_MCP_IMAGE	registry.example/pulselink-mcp@sha256:<digest>
ENABLE_OTEL	True
OTEL_EXPORTER_OTLP_ENDPOINT	http://localhost:8080/api/public/otel
OTEL_EXPORTER_OTLP_PUBLIC_KEY_REF	secret://observability/otel/public-key
OTEL_EXPORTER_OTLP_SECRET_KEY_REF	secret://observability/otel/secret-key
OTEL_EXPORTER_OTLP_PROTOCOL	http/protobuf
EUNOMIA_TYPE	none	options: none, embedded, remote
EUNOMIA_POLICY_FILE	mcp_policies.json
EUNOMIA_REMOTE_URL	http://eunomia-server:8000
PROVIDER	—	operator-selected model provider
MODEL_ID	—	operator-selected model capability
PULSETOOL	True	These names match the authoritative "Toggle Env Var" column in the README MCP tools table (condensed action-routed surface).
SOURCE_CREDENTIALS	{"x":{"type":"cookie_session","secret":"vault://pulselink/x/session"},"reddit":{"type":"oauth2","secret":"vault://pulselink/reddit/token","token_url":"https://www.reddit.com/api/v1/access_token","client_id":"<id>","client_secret_secret":"vault://pulselink/reddit/cs"},"github":{"type":"api_key","secret":"env://GITHUB_TOKEN","prefix":"token "},"exa":{"type":"api_key","secret":"env://EXA_API_KEY","prefix":""}}	Keyless sources (youtube, web, rss, news, hackernews, v2ex, bilibili) need NOTHING here. Auth-laddered sources light up their higher-fidelity backend when a credential is set. SOURCE_CREDENTIALS is a JSON object mapping a source -> credential descriptor; secret values are URI refs resolved via the injected secrets backend (vault://, env://). Example:

Inherited agent-connector-sdk variables (apply to every connector)

Variable	Example	Description
MCP_TOOL_MODE	intent	Tool surface: intent | condensed | verbose | both
MCP_ENABLED_TOOLS	—	Comma-separated tool allow-list
MCP_DISABLED_TOOLS	—	Comma-separated tool deny-list
MCP_ENABLED_TAGS	—	Comma-separated tag allow-list
MCP_DISABLED_TAGS	—	Comma-separated tag deny-list
MCP_CLIENT_AUTH	—	Outbound MCP child auth: oidc-client-credentials | basic | none
OIDC_CLIENT_ID	—	OIDC client id (service-account auth)
OIDC_CLIENT_SECRET_REF	secret://identity/oidc-client-secret	Runtime secret reference for the OIDC service account
MCP_BASIC_AUTH_USERNAME	—	HTTP Basic username (MCP_CLIENT_AUTH=basic)
MCP_BASIC_AUTH_PASSWORD_REF	secret://identity/mcp-basic-password	Runtime secret reference for HTTP Basic auth (MCP_CLIENT_AUTH=basic)
DEBUG	False	Verbose logging
PYTHONUNBUFFERED	1	Unbuffered stdout (recommended in containers)
MCP_URL	http://localhost:8000/mcp	URL of the MCP server the agent connects to

27 package + 14 inherited variable(s). Auto-generated from .env.example + the shared agent-connector-sdk set — do not edit.

Every variable the server reads.

MCP server / transport

Variable	Description	Default
TRANSPORT	stdio, streamable-http, or sse	stdio
HOST	Bind host (HTTP transports)	0.0.0.0
PORT	Bind port (HTTP transports)	8000
MCP_TOOL_MODE	Tool surface: condensed, verbose, or both	condensed
MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS	Comma-separated tool allow/deny list	—
MCP_ENABLED_TAGS / MCP_DISABLED_TAGS	Comma-separated tag allow/deny list	—
DEBUG	Verbose logging	False
PYTHONUNBUFFERED	Unbuffered stdout (recommended in containers)	1

X / xAI Live Search (optional)

Used only by the optional X live-search capability. Its model identifier is operator-supplied; keyless and non-model source paths do not require it.

Variable	Description	Default

Source credentials (keyless-first)

Variable	Description	Default
SOURCE_CREDENTIALS	JSON object mapping a source → credential descriptor (secret values are URI refs resolved via the secrets backend: vault://, env://, sqlite://). Keyless sources (youtube, web, rss, news, hackernews, v2ex, bilibili) need nothing here; auth-laddered sources (x, reddit, github, exa…) light up higher-fidelity backends when set.	—

Tool toggles

Each action-routed tool can be disabled individually via its toggle env var (set to false). The full list is in the Available MCP Tools table above.

Variable	Description	Default
PULSETOOL	Enable the PulseLink source tools (pulse_search / pulse_list / pulse_fetch / pulse_transcribe / pulse_status)	True

Telemetry & governance

Variable	Description	Default
ENABLE_OTEL	Enable OpenTelemetry export	True
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP collector endpoint	—
OTEL_EXPORTER_OTLP_PUBLIC_KEY / OTEL_EXPORTER_OTLP_SECRET_KEY	OTLP auth keys	—
OTEL_EXPORTER_OTLP_PROTOCOL	OTLP protocol (e.g. http/protobuf)	—
EUNOMIA_TYPE	Authorization mode: none, embedded, remote	none
EUNOMIA_POLICY_FILE	Embedded policy file	mcp_policies.json
EUNOMIA_REMOTE_URL	Remote Eunomia server URL	—

Installation

Pick the extra that matches what the operator want to run:

Extra	Installs	Use when
pulselink-mcp[mcp]	Connector-focused MCP server (agent-connector-sdk — FastMCP/FastAPI + epistemic-graph[full])	The operator only run the MCP server (smallest install / image)
pulselink-mcp[all]	Everything (mcp + agent + logfire + the youtube/feeds/audio source extras)	Development / both surfaces

# Connector-focused MCP server (includes the shared graph engine)
uv pip install "pulselink-mcp[mcp]"

# Agent runtime (adds model orchestration to the shared graph engine)

# Everything (development)
uv pip install "pulselink-mcp[all]"      # or: python -m pip install "pulselink-mcp[all]"

The optional source extras (youtube → yt-dlp, feeds → feedparser, audio → faster-whisper) are lazy-imported; the keyless web/forum/news/dev sources need none of them. Install pulselink-mcp[sources] for youtube + feeds.

Container images (:mcp)

One multi-stage docker/Dockerfile builds the MCP-only image (--target mcp):

Image tag	Build target	Contents	Entrypoint
example/pulselink-mcp:mcp	--target mcp	pulselink-mcp[mcp] — connector-focused, includes epistemic-graph[full]; no model-orchestration stack	pulselink-mcp

docker build --target mcp   -t example/pulselink-mcp:mcp    docker/   # connector-focused MCP server

agent (immutable agent digest) with a co-located :mcp sidecar.

Knowledge-graph database (epistemic-graph)

Agent Connector SDK core dependency (epistemic-graph[full]). The [mcp] extra keeps deployments can use the bundled engine. For production or shared state, run epistemic-graph as a dedicated database service and configure the runtime to use it. Deployment recipes (single-node + Raft HA), connection configuration, and architecture diagrams are documented in the epistemic-graph deployment guide.

Deploy with agent-connector-sdk-deployment

Provision this package with the consolidated agent-connector-sdk-deployment workflow. It selects an installed-package, editable-source, or immutable-container path; records only runtime secret and TLS-profile references in AgentConfig; and runs doctor, registration, policy, observability, and rollback gates. Ask your agent to "deploy pulselink-mcp with agent-connector-sdk-deployment".

Install mode	Command
Installed package	uv tool install "pulselink-mcp[mcp]", then run pulselink-mcp
Immutable container	deploy registry.example.invalid/pulselink-mcp@sha256:<digest> through the operator-selected orchestrator

The repository embeds no deployment profile, credential value, certificate path, or environment-specific endpoint. Supply those at runtime through AgentConfig and the configured secret provider.

Governed capability contract

This package ships a compact canonical skill surface with specialist procedures kept as referenced workflows. The current MCP tools, skill metadata, connector_manifest.yml, ontology, mappings, shapes, fixtures, migrations, tool-schema fingerprints, and certification metadata form one versioned capability contract. Validate them together; do not rely on stale tool names or historical per-task skill wrappers.

Runtime endpoints, credentials, certificate trust, tenant identity, retention, and observability policy are deployment inputs and are never packaged values. See Configuration, trust, and privacy before enabling a network transport, connector ingestion, Arbora delegation, or trace export.