GitHub - agentralabs/agentic-connect: Universal external interface engine for AI agents — 123 MCP tools, 18 protocols, Connection Souls, Intelligent Retry, Encrypted Vault

Universal external interface engine for AI agents.

Every protocol understood. Every connection remembered. Every failure classified. Automatically.

Problems Solved · Quickstart · How It Works · Connection Souls · Intelligent Retry · MCP Tools · Benchmarks · Engine · Install · API · Paper

Every AI agent is isolated.

Claude can reason about your infrastructure but can't SSH into it. GPT can design an API integration but can't test the endpoint. Your copilot writes database queries but can't check if the server is healthy. Every external operation requires a separate tool, separate auth, separate retry logic. None of them learn from past connections.

The current fixes don't work. Protocol-specific libraries handle one protocol each -- you need reqwest for HTTP, russh for SSH, sqlx for Postgres, lettre for email. Each starts from zero knowledge. API platforms like Postman are HTTP-only. Integration platforms like Zapier require pre-built integrations for every service. Infrastructure tools like Terraform manage provisioning but not real-time connectivity.

AgenticConnect gives your agent a single engine that reaches any external system. Not "call this HTTP endpoint." Your agent has reach -- 18 protocol families, 8 authentication methods, circuit breakers, failure classification, and Connection Souls that remember every system it has ever touched. One engine. 123 MCP tools. Works with Claude, Cursor, Windsurf, or any MCP client.

Problems Solved (Read This First)

Problem: every protocol requires a different library -- HTTP, SSH, DB, email, queues all need separate code. Solved: one engine handles 18 protocol families with auto-detection from URL, port, or server banner.
Problem: every connection starts from zero -- no memory of past latency, errors, or server capabilities. Solved: Connection Souls accumulate OS fingerprints, performance baselines, error histories across sessions.
Problem: retry logic is hardcoded "retry 3x with backoff" for all failures, wasting time on permanent errors. Solved: five-class failure classification (transient, permanent, rate-limit, auth, network) with strategy per class.
Problem: credentials scattered across env vars, config files, and hardcoded strings. No encryption at rest. Solved: encrypted vault (AES-256-GCM, PBKDF2 100K iterations) stores all 8 auth types with auto-refresh for OAuth2.
Problem: a failing API cascades into system-wide failures -- retry storms amplify the outage. Solved: per-endpoint circuit breakers open after N failures, isolating unhealthy endpoints automatically.
Problem: LLMs can't reach external systems natively -- they generate code but can't execute connections. Solved: 123 MCP tools over stdio. Any LLM that speaks MCP gets instant access to every protocol.

# Your agent connects to anything
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"connect_protocol_detect","arguments":{"target":"https://api.github.com"}}}' | agentic-connect-mcp

# Make live API calls with circuit breaker protection
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"connect_api_call","arguments":{"url":"https://httpbin.org/get"}}}' | agentic-connect-mcp

# Query a database with schema discovery
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"connect_db_connect","arguments":{"url":"sqlite:///tmp/app.db","name":"mydb"}}}' | agentic-connect-mcp

# Verify webhook HMAC signatures
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"connect_webhook_verify","arguments":{"payload":"data","signature":"abc","secret":"key"}}}' | agentic-connect-mcp

One binary. 123 tools. Every protocol. Works with Claude, GPT, or any LLM you switch to next.

Connection Souls

Every connection in AgenticConnect accumulates a soul -- a persistent profile stored in SQLite that grows richer with each interaction.

What a Soul Contains

System fingerprint -- OS, server software, versions, supported protocols, timezone, detected services. Populated on first connection through banner analysis and response headers.
Performance baseline -- Running averages for latency (P50, P95, P99), throughput, and error rate. Updated after every request.
Error history -- Last 100 errors per connection with timestamp, error type, HTTP status code, and resolution status. History is bounded by evicting the oldest entries.
Capability map -- Key-value store for discovered capabilities (e.g., docker: installed, python: 3.11, disk: 80% used).

What Souls Enable

Before connecting, your agent already knows the system:

> soul inspect api.github.com
  OS: Linux
  Server: nginx/1.20
  TLS: 1.3
  Avg latency: 42ms (baseline: 45ms -- normal)
  Error rate: 0.1%
  Last error: rate limit 3 days ago
  Rate limit: 5000/hr (resets hourly)
  Circuit: CLOSED (0/5 failures)

This context informs retry strategies, request timing, and operational decisions. An agent with Connection Souls knows to avoid peak hours for a server that historically times out between 2-4 PM UTC.

Intelligent Retry

Every failure is classified and handled with the right strategy. No blind retries.

Five-Class Failure Taxonomy

Class	Indicators	Strategy	Max Retries
Transient	503, timeout, connection reset	Exponential backoff (1s × 2^n, max 30s)	3
Permanent	404, 400, 405, 410, 422	Fail fast -- don't waste time	0
RateLimit	429 + Retry-After header	Wait the server-specified duration	1
AuthFailure	401, 403	Refresh OAuth2 token, then retry once	1
NetworkError	DNS failure, connection refused	Exponential backoff (2s × 2^n, max 60s)	5

Circuit Breakers

Per-endpoint circuit breakers prevent cascade failures:

Closed (normal): requests pass through. Each failure increments a counter.
Open: after 5 consecutive failures, all requests are rejected immediately. A timer starts.
Half-Open: after 60 seconds, a single probe request is allowed. Success → Closed; failure → Open.

# Simulate failure classification
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"connect_retry_simulate","arguments":{"http_status":429}}}' | agentic-connect-mcp
# → {"classification": "RateLimit", "strategy": "WaitRetryAfter"}

# View circuit breaker state
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"connect_retry_circuit","arguments":{"endpoint":"https://api.example.com","action":"view"}}}' | agentic-connect-mcp

MCP Tools

AgenticConnect exposes 123 MCP tools organized into 11 capability domains:

Protocol Tools (4)

Tool	Description
`connect_protocol_detect`	Detect protocol from URL, host:port, or hostname
`connect_protocol_list`	List all 18 supported protocols with capabilities
`connect_protocol_test`	Test if a protocol endpoint is reachable
`connect_protocol_caps`	Get protocol capabilities (streaming, pub-sub, TLS)

Auth + Credential Vault Tools (5)

Tool	Description
`connect_auth_configure`	Configure auth for a connection (8 methods)
`connect_auth_test`	Test if credentials are valid and not expired
`connect_auth_refresh`	Force OAuth2 token refresh
`connect_auth_rotate`	Rotate credentials without service interruption
`connect_auth_vault`	Manage encrypted credential vault (list/store/retrieve/delete)

Connection Soul Tools (5)

Tool	Description
`connect_soul_inspect`	View accumulated knowledge about a remote system
`connect_soul_refresh`	Force re-scan of remote system capabilities
`connect_soul_history`	View connection history and error patterns
`connect_soul_predict`	Predict likely issues based on past patterns
`connect_soul_compare`	Compare two systems for migration planning

Retry + Circuit Breaker Tools (5)

Tool	Description
`connect_retry_configure`	Set retry policies per connection
`connect_retry_status`	View all circuit breaker states and recent failures
`connect_retry_patterns`	View learned failure patterns for an endpoint
`connect_retry_circuit`	View or reset circuit breaker state
`connect_retry_simulate`	Simulate failure to test classification

API + GraphQL Tools (11)

Tool	Description
`connect_api_call`	Make HTTP API call with auth, retry, and circuit breaker
`connect_api_discover`	Discover API endpoints by probing common paths
`connect_api_test`	Test endpoint against expected status/body
`connect_api_spec`	Parse OpenAPI/Swagger specification
`connect_api_profile`	View behavioral profile of an API
`connect_api_mock`	Generate mock server from API profile
`connect_graphql_query`	Execute GraphQL query with variables
`connect_graphql_introspect`	Discover GraphQL schema
`connect_graphql_build`	Build query from natural language
`connect_graphql_subscribe`	Manage real-time subscriptions
`connect_graphql_normalize`	Flatten nested response data

Database Tools (6)

Tool	Description
`connect_db_connect`	Connect to database with auto-type detection
`connect_db_query`	Execute SQL query with result formatting
`connect_db_schema`	Discover database schema (tables, columns, types)
`connect_db_health`	Monitor database health, row counts, connection status
`connect_db_optimize`	Suggest query optimizations via EXPLAIN QUERY PLAN
`connect_db_migrate`	Detect schema changes

Security Tools (11)

Tool	Description
`connect_tls_inspect`	Inspect TLS configuration of any host
`connect_tls_grade`	Grade TLS quality (A-F)
`connect_tls_expiry`	Check certificate expiry for multiple hosts
`connect_tls_certificates`	List and monitor all known certificates
`connect_tls_audit`	Audit cipher suites and TLS protocol versions
`connect_sentinel_probe`	Health check any endpoint across protocols
`connect_sentinel_status`	View aggregate health across all monitored services
`connect_sentinel_monitor`	Start continuous monitoring
`connect_sentinel_trends`	View performance trends over time
`connect_sentinel_alert`	Configure alert thresholds
`connect_sentinel_report`	Generate availability report

Remaining tool domains (Browser 16, Infra 16, Comms 16, Data Channels 10, Intelligence 18)

See docs/public/mcp-tools.md for the complete 123-tool reference covering browser automation, web scraping, form filling, SSH remote execution, service mesh, containers, email, telephony, webhooks, message queues, cloud storage, TLS, network monitoring, failure prediction, API evolution tracking, idle maintenance, and collective learning.

Benchmarks

Rust core. SQLite persistence. Zero-copy where possible. Real numbers:

Operation	Time	Scale
Tool dispatch (registry lookup)	< 1 μs	123 tools
Failure classification (HTTP status)	< 1 μs	5 classes
Circuit breaker check	< 1 μs	per endpoint
HMAC-SHA256 sign	~2 μs	1 KB payload
Connection store insert	~50 μs	SQLite
AES-256-GCM encrypt	~150 μs	100 KB payload
Database schema discovery	~5 ms	50 tables

All benchmarks measured on Apple M4 Pro, Rust release mode. Sub-microsecond latencies validated by paper-claim tests running 10,000 iterations.

Comparison with existing approaches

	curl	reqwest	Postman	Zapier	AgenticConnect
Protocols	1 (HTTP)	1 (HTTP)	1 (HTTP)	Multi (service)	18 families
Auth management	Manual	Manual	GUI	Pre-built	8 methods + vault
Failure learning	None	None	None	None	5-class + souls
Circuit breakers	None	None	None	None	Per-endpoint
MCP access	No	No	No	No	123 tools
Dependencies	OS tool	Rust crate	Desktop app	Cloud service	None

The Connection Engine

8 engine modules handle all external operations:

Engine	Lines	What it does
ConnectionStore	348	SQLite persistence -- connections, profiles, health checks, tags
RetryEngine	226	Circuit breakers, failure classification, rate limit tracking, pattern learning
CredentialVault	196	AES-256-GCM encrypted storage, PBKDF2 key derivation, 8 auth methods
DbConnection	181	SQLite query execution, schema discovery, EXPLAIN QUERY PLAN optimization
ProtocolDetect	138	URL scheme parsing, TCP banner reading, port-based detection for 18 protocols
HttpClient	115	reqwest wrapper with timing, rate limit header extraction, circuit breaker integration
WebhookEngine	104	HMAC-SHA256 sign/verify, constant-time comparison, delivery tracking
TlsInspect	85	Certificate checking, TLS quality grading, multi-host expiry monitoring

All files under 400 lines. Largest: store.rs at 348.

Install

One-liner (desktop profile, backwards-compatible):

curl -fsSL https://agentralabs.tech/install/connect | bash

Downloads a pre-built agentic-connect-mcp binary to ~/.local/bin/ and merges the MCP server into your Claude Desktop and Cursor configs. Requires curl. If release artifacts are not available, the installer automatically falls back to cargo install --git source install.

Environment profiles (one command per environment):

# Desktop MCP clients (auto-merge Claude Desktop + Cursor when detected)
curl -fsSL https://agentralabs.tech/install/connect/desktop | bash

# Terminal-only (no desktop config writes)
curl -fsSL https://agentralabs.tech/install/connect/terminal | bash

# Remote/server hosts (no desktop config writes)
curl -fsSL https://agentralabs.tech/install/connect/server | bash

Channel	Command	Result
GitHub installer (official)	`curl -fsSL https://agentralabs.tech/install/connect \| bash`	Installs release binaries when available, otherwise source fallback; merges MCP config
GitHub installer (desktop)	`curl -fsSL https://agentralabs.tech/install/connect/desktop \| bash`	Explicit desktop profile behavior
GitHub installer (terminal)	`curl -fsSL https://agentralabs.tech/install/connect/terminal \| bash`	Installs binaries only; no desktop config writes
GitHub installer (server)	`curl -fsSL https://agentralabs.tech/install/connect/server \| bash`	Installs binaries only; server-safe behavior
crates.io	`cargo install agentic-connect-mcp`	Installs MCP server binary

Standalone guarantee: AgenticConnect works independently -- no other Agentra sister required.

Build from source

git clone https://github.com/agentralabs/agentic-connect.git
cd agentic-connect
cargo build --release -j 1
cp target/release/agentic-connect-mcp ~/.local/bin/

MCP Server

Any MCP-compatible client gets instant access to 18 protocol families. The agentic-connect-mcp crate exposes the full engine over the Model Context Protocol (JSON-RPC 2.0 over stdio).

Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "agentic-connect": {
      "command": "agentic-connect-mcp",
      "args": []
    }
  }
}

Configure Cursor / Windsurf

Add to ~/.cursor/mcp.json or ~/.windsurf/mcp.json:

{
  "mcpServers": {
    "agentic-connect": {
      "command": "agentic-connect-mcp",
      "args": []
    }
  }
}

What the LLM gets

Category	Count	Examples
Tools	123	`connect_api_call`, `connect_db_query`, `connect_protocol_detect`, `connect_tls_grade`, `connect_webhook_verify`, `connect_retry_simulate` ...

Once connected, the LLM can make API calls, query databases, detect protocols, verify webhooks, manage credentials, and monitor infrastructure -- all backed by Connection Souls, circuit breakers, and an encrypted credential vault. Full MCP tool reference ->

Quickstart

Detect and connect -- 1 tool call

# Auto-detect protocol from URL
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"connect_protocol_detect","arguments":{"target":"https://api.stripe.com"}}}' | agentic-connect-mcp
# → {"detected": true, "protocol": "HTTPS", "port": 443, "capabilities": {"request_response": true, "supports_tls": true}}

Live API call with circuit breaker

echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"connect_api_call","arguments":{"url":"https://httpbin.org/get","method":"GET"}}}' | agentic-connect-mcp
# → {"status": 200, "latency_ms": 142, "body": "...", "headers": {"x-ratelimit-remaining": "99"}}

Check TLS security grade

echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"connect_tls_grade","arguments":{"host":"github.com"}}}' | agentic-connect-mcp
# → {"host": "github.com", "grade": "B+", "tls_available": true}

Query a database

echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"connect_db_connect","arguments":{"url":"sqlite:///tmp/app.db","name":"appdb"}}}' | agentic-connect-mcp
# → {"connected": true, "db_type": "Sqlite", "tables": 5}

echo '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"connect_db_query","arguments":{"name":"appdb","query":"SELECT COUNT(*) as cnt FROM users"}}}' | agentic-connect-mcp
# → {"columns": ["cnt"], "rows": [{"cnt": 1247}], "row_count": 1}

How It Works

AgenticConnect is structured as a layered system: the MCP server receives JSON-RPC requests from LLMs, dispatches them through a tool registry to 11 tool modules, which call into 8 engine modules backed by SQLite persistence.

The core runtime is written in Rust for performance and safety. All state lives in a single SQLite database -- no external services, no cloud dependencies. The MCP server exposes the full engine over JSON-RPC stdio.

Supported protocols -- 18 families:

Protocol	Default Port	Capabilities
HTTP/HTTPS	80/443	Request-response, compression
WebSocket/WSS	80/443	Bidirectional, streaming, pub-sub
gRPC	443	Bidirectional, streaming, TLS
SSH/SFTP	22	Bidirectional, remote execution
FTP	21	File transfer
SMTP	587	Email sending
IMAP	993	Email reading, TLS
DNS	53	Name resolution
MQTT	1883	IoT pub-sub, streaming
AMQP	5672	Message queue, pub-sub
Redis	6379	Key-value, pub-sub
PostgreSQL	5432	Database wire protocol
MySQL	3306	Database wire protocol
TCP/UDP	--	Raw transport

Authentication -- 8 methods with encrypted vault:

Method	Lifecycle	Token Management
None	--	--
Basic	Static	Username/password
Bearer	Static	API key or JWT
API Key	Static	Header or query parameter
OAuth 2.0	Auto-refresh	4 grant types, expiry detection
SSH Key	Static	Public/private keypair
SSH Password	Static	Username/password
Mutual TLS	Cert expiry	Client certificate

Validation

This isn't a prototype. It's tested at scale.

Suite	Tests
Engine unit tests (8 modules)	27	Store, retry, vault, DB, HTTP, protocol, TLS, webhook
Core type validation	21	Protocol, connection, auth, retry, soul, serialization
Edge case tests	29	Boundary conditions, error paths, malformed input
Stress tests	11	1K connections, 10K failures, 100KB crypto, 1K HMAC
Paper claim validation	20	Every number in the paper verified by code
MCP protocol compliance	14	JSON-RPC parsing, error codes, response format
Tool registry validation	14	123 tools listed, no duplicates, verb-first descriptions
Tool execution (phase 2)	24	Every tool group exercised with real session
Session management (phase 3)	11	Store, retry, vault, DB lifecycle, multi-connection
Integration workflows (phase 4)	10	End-to-end MCP flows, multi-tool sequences
Total	181	All passing

One research paper:

Paper I: Universal Connectivity -- protocol detection, Connection Souls, retry fabric (6 pages, 3 TikZ figures, 9 tables, 18 references)

Repository Structure

agentic-connect/
├── Cargo.toml                     # Workspace root
├── crates/
│   ├── agentic-connect/           # Core library (types + 8 engines)
│   ├── agentic-connect-mcp/       # MCP server (123 tools over stdio)
│   ├── agentic-connect-cli/       # CLI binary (acnx)
│   └── agentic-connect-ffi/       # FFI bindings (C-compatible)
├── paper/                         # Research paper (LaTeX + PDF)
├── assets/                        # 7 SVGs (Agentra design system)
├── docs/                          # 8 documentation pages
├── scripts/                       # Installer + 3 guardrails
└── .github/workflows/             # 5 CI workflows

Running Tests

# All workspace tests
cargo test --workspace

# Core engine tests only
cargo test -p agentic-connect

# MCP server + tool tests
cargo test -p agentic-connect-mcp

Project Stats


Lines of Code	6,203 (core + MCP + CLI + FFI)
Test Coverage	164+ tests (181 including integration)
Supported Clients	4 (Claude, Cursor, Windsurf, Cody)
MCP Tools	123 across 11 domains
Protocol Families	18
Auth Methods	8
Engine Modules	8

Environment Variables

Variable	Default	Description
`ACNX_DATA_DIR`	`~/.local/share/agentic-connect`	Data directory for SQLite and profiles
`ACNX_LOG_LEVEL`	`warn`	Log level (trace, debug, info, warn, error)
`RUST_LOG`	--	Alternative log level control

Contributing

See CONTRIBUTING.md. The fastest ways to help:

Try it and file issues
Add a protocol adapter -- implement an engine for a new protocol
Write an example -- show a real use case
Improve docs -- every clarification helps someone

Privacy and Security

All data stays local in SQLite -- no telemetry, no cloud sync.
Credentials encrypted at rest (AES-256-GCM, PBKDF2 100K iterations).
No secrets ever returned in MCP tool responses -- only summaries.
Circuit breakers prevent retry storms from amplifying outages.
See SECURITY.md for vulnerability reporting.

_{Built by Agentra Labs}

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
.github/workflows		.github/workflows
assets		assets
crates		crates
docs		docs
paper/paper-i-universal-connectivity		paper/paper-i-universal-connectivity
scripts		scripts
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md

Folders and files

Latest commit

History

Repository files navigation

Every AI agent is isolated.

Problems Solved (Read This First)

Connection Souls

What a Soul Contains

What Souls Enable

Intelligent Retry

Five-Class Failure Taxonomy

Circuit Breakers

MCP Tools

Protocol Tools (4)

Auth + Credential Vault Tools (5)

Connection Soul Tools (5)

Retry + Circuit Breaker Tools (5)

API + GraphQL Tools (11)

Database Tools (6)

Security Tools (11)

Benchmarks

The Connection Engine

Install

Build from source

MCP Server

Configure Claude Desktop

Configure Cursor / Windsurf

What the LLM gets

Quickstart

Detect and connect -- 1 tool call

Live API call with circuit breaker

Check TLS security grade

Query a database

How It Works

Validation

Repository Structure

Running Tests

Project Stats

Environment Variables

Contributing

Privacy and Security

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages