Skip to main content
Glama
AgentSecure Community

AgentSecure Community

Official

AgentSecure Community

By ShellFrame AI

PyPI CI License

Make credential-bearing HTTP(S) requests from Claude Code and Codex through MCP, using placeholders instead of raw credentials in project files and MCP responses.

AgentSecure imports dotenv secrets into a local vault, checks destinations, and injects credentials when sending approved requests. It is not an OS sandbox or a system-wide firewall: the local user and machine remain trusted.

Try it with a fake credential first

No API account, real credentials, or coding-agent installation is needed for this local MCP demo. With Python 3.8+ installed:

git clone https://github.com/ShellFrameAI/agentsecure-community.git
cd agentsecure-community
python3 examples/mcp_fake_secret_demo.py

The demo creates a temporary project and vault, imports a fake credential, and calls a loopback HTTP fixture through the actual MCP stdio server. It checks the result before printing:

Project file: DEMO_API_KEY=AGENTSECURE_ALIAS_DEMO_API_KEY
Approved fixture: received the fake credential
MCP response: Bearer [redacted]
Unapproved destination: blocked
Demo passed; temporary project and vault removed.

Only the temporary fixture policy permits loopback traffic. The demo does not change your project, client configuration, or normal vault, and does not contact an external API. This demonstrates the managed MCP flow, not isolation from an unrestricted process running as your local user.

AGENTSECURE_ALIAS_* values are non-secret project-file placeholders; ${DEMO_API_KEY} is the placeholder used in an MCP request. Neither is a real provider credential. Internal virt_* bindings are separate from these aliases.

Related MCP server: Janee

Why AgentSecure

AI coding agents can access .env files, shell environments, MCP configuration, and local credentials. Ignore files are not a security boundary. AgentSecure keeps real secrets outside the agent's normal project and MCP context.

Quick Start

After trying the demo, run these commands from the project you want to configure. You need Python 3.8+, uv, and your chosen coding-agent CLI. Use least-privilege development credentials. Before importing, review the vault and backup behavior: dotenv backups are plaintext, with owner-only permissions, under your home directory.

1. Install AgentSecure

uv tool install agentsecure

2. Optionally scan the project

agentsecure scan .

The scan is local and does not change the project.

3. Run guided setup once

For Claude Code:

agentsecure start --client claude

Follow the printed MCP configuration step, then start Claude Code normally:

claude

For Codex:

agentsecure start --client codex --install-mcp

Then start Codex normally:

codex

agentsecure start is guided one-time project setup. It initializes the project, offers to move .env secrets into the local vault, writes persistent agent guidance, and prints or installs the selected MCP configuration.

It is not a persistent background service. After setup finishes, start Claude Code or Codex normally. You do not normally wrap the agent with agentsecure run.

4. Verify a fresh agent session

Restart the coding agent after applying the MCP configuration. Ask it to inspect the AgentSecure setup and call agentsecure.policy.describe and agentsecure.secret.status without printing secret values. Confirm it sees the AgentSecure MCP tools. agentsecure doctor checks local setup, but does not prove that the client loaded MCP. Claude setup prints a configuration step; Codex setup above requests automatic MCP installation.

For a credential-bearing request, use agentsecure.http.request with a ${ENV_NAME} placeholder and an approved destination. Ordinary requests without secret placeholders should use the agent's normal networking tools. See the MCP usage guide.

How It Works

  1. During setup, real secrets are moved into the local AgentSecure vault.

  2. Project files receive aliases or safe placeholders instead of real values.

  3. The coding agent starts and runs normally.

  4. Secret-bearing requests use the AgentSecure MCP tool.

  5. AgentSecure validates the destination and injects the real secret while sending the request outside the agent's context.

Security Boundaries

AgentSecure helps protect against:

  • exposing raw secrets to the coding agent through the default MCP flow;

  • keeping real secrets in agent-readable project files;

  • sending protected secrets to destinations that are not approved by policy.

AgentSecure is not:

  • a complete operating-system sandbox;

  • a VM or container;

  • protection from an attacker who already controls the local user or machine;

  • a replacement for endpoint, identity, network, or cloud security controls.

The local user and machine remain inside the trust boundary. See the security model and limitations for the full threat model.

Documentation

License

Licensed under the Apache License 2.0. See LICENSE.

Available Tools

13 tools
agentsecure.audit_contextA

Inspect recent local Mesh history for troubleshooting messages, registrations, approvals, or policy denials. Returns an events array containing only mesh.* records from the configured audit log, optionally filtered by resource, with the last limit matches in log order (oldest first within that slice). A missing log returns an empty array and malformed JSON lines are skipped. Does not change state or include non-Mesh HTTP/secret audit events. Text fields may be redacted with summary/hash metadata; this is not an immutable audit service. Example: {"limit": 10}.

Inputs: limit, resource.

agentsecure.check_messagesA

Check local inbox counts before answering whether this agent has messages or approvals. Returns agent_id, unread_count, pending_approval_count, and a notice, not message content. Pending approvals are those assigned to the agent or its registered team, not all requests created by it. Does not mark messages read. Use agentsecure.list_messages for records and agentsecure.read_message to acknowledge one. Example: {"agent_id": "backend-agent"}.

Inputs: agent_id (required).

agentsecure.get_approval_statusA

Read a previously created local approval without changing it. Returns an approval object with status (pending, approved, denied, or needs_info), action/resource, required_approver, and recorded decision details/timestamps. Reason text remains redacted with summary/hash metadata. Unknown IDs cause an error. This tool neither requests nor grants approval, and an approved record does not execute an action or automatically lift policy restrictions. Use agentsecure.request_approval to create a request and agentsecure.get_policy_hint to inspect current action policy.

Inputs: approval_id (required).

agentsecure.get_policy_hintA

Evaluate a proposed Mesh action against the current local agent policy without executing it. Checks cannot, can_message (when a send_message target is supplied), requires_human_for, and sensitive markers in action/resource. Returns allowed, blocked, reason, action, sanitized resource, and allowed_next_step. This is guidance, not an authorization token or a guarantee about external permissions; existing approval records are not consulted. Use agentsecure.request_approval to record a review request, or agentsecure.policy.describe for HTTP network/secret configuration. Example: {"agent_id": "frontend-agent", "action": "send_message", "target": "backend-agent"}.

Inputs: action (required), agent_id (required), target, resource.

agentsecure.http.requestA

Send one HTTP(S) request that needs a configured secret, using ${ENV_NAME} placeholders instead of raw credentials. Checks project destination policy before resolving secrets and applies configured vault-alias host restrictions; calls without placeholders are blocked (use ordinary network tools for those). Performs the requested remote operation, does not follow redirects, and revokes temporary alias grants afterward. Returns blocked=false, status, reason, headers, and a UTF-8 body, with response body/header values sanitized for known secrets; HTTP error statuses are still responses. Blocked calls return blocked=true, reason, rule_id, and sometimes allow_command; configuration errors may instead be MCP errors. This is not a sandbox for other network tools. Example: {"url": "https://api.example.com/me", "headers": {"Authorization": "Bearer ${API_KEY}"}} requires that host and API_KEY to be configured and approved.

Inputs: url (required), ttl, body, json, +5 more.

agentsecure.identityA

Look up or register identities in the local Community Mesh store. By default, agent_id returns exists plus that identity's metadata (or exists=false if unknown); omitting agent_id returns an agents array sorted by ID. Set register=true with a non-empty agent_id to create or overwrite its record and write an audit event; returns the saved identity. Registration replaces rather than merges metadata. Identity labels, trust_level, and allowed_scopes do not authenticate callers or grant permissions. Example: {"agent_id": "backend-agent"}.

Inputs: name, team, type, owner, +5 more.

agentsecure.list_messagesA

List messages addressed to one agent in the local Community Mesh store. Returns agent_id and a messages array, newest first (empty if none). Each record includes message_id, sender/recipient, subject, resource, status, thread IDs, and timestamps. Body is [redacted]; body_summary may retain up to 120 characters and body_sha256 is a digest, not recoverable full content. Does not mark messages read. Use agentsecure.check_messages for counts only or agentsecure.read_message to mark a specific record read. Example: {"agent_id": "backend-agent", "include_read": true}.

Inputs: agent_id (required), include_read.

agentsecure.policy.describeA

Inspect the current project's network rules and configured secret metadata before a secret-bearing HTTP request. Takes no arguments. Returns network (allowed domains/ports and IP restrictions), secret_aliases, project_bindings, and usage instructions; no secret values. Does not change policy or verify that credentials work. Use agentsecure.secret.status for one env name, or agentsecure.get_policy_hint for a Mesh action rather than HTTP destination policy.

Inputs: no named parameters.

agentsecure.read_messageA

Retrieve and acknowledge one local Mesh message after listing the inbox. Requires agent_id to match the record's recipient; an unknown ID or a different recipient causes an error. Returns the message record with status=read and read_at; the first read updates local state and audit. Re-reading returns the same acknowledged record. Body remains [redacted], with only body_summary/body_sha256 available; this does not recover original text. Use agentsecure.list_messages to inspect without marking read. The recipient check compares caller-supplied IDs, not authenticated identities.

Inputs: agent_id (required), message_id (required).

agentsecure.reply_messageA

Reply to a local Mesh message addressed to from_agent. Marks the original read first, then checks send_message policy and creates a type=reply message to the original sender, preserving thread_id and resource and setting reply_to. Returns blocked=false and message, or a policy denial with blocked=true, reason, and allowed_next_step; the original can remain read even if sending is blocked. Unknown messages or recipient mismatches cause an error. Reply body is redacted with a summary/hash, not full-text delivery. Use agentsecure.send_message for a new thread.

Inputs: body (required), from_agent (required), message_id (required).

agentsecure.request_approvalA

Create a local pending approval record when a Mesh policy hint requires human review. Returns an approval object with approval_id, status=pending, requested_by, action, resource, required_approver, and timestamps; reason is redacted with a summary/hash. Writes local state and audit but does not send a message, notify a human, execute the action, or change policy. Repeated calls create separate requests. Use agentsecure.get_approval_status with the returned ID; approval decisions are made outside these MCP tools. An approved record does not automatically unblock policy. Example: {"requested_by": "frontend-agent", "action": "deploy_preview", "reason": "Please review the preview deployment."}.

Inputs: action (required), reason (required), requested_by (required), resource, +1 more.

agentsecure.secret.statusA

Check whether one environment name is assigned in the current project's secret configuration before using its ${ENV_NAME} placeholder. Returns exists and env_name; when configured, also returns source (vault_alias or project_binding), provider, mode, and alias metadata when applicable. This is a configuration lookup, not a vault-value or credential-validity check, and returns no secret value. Use agentsecure.policy.describe to list all configured aliases and bindings. Example: {"env_name": "API_KEY"}.

Inputs: env_name (required).

agentsecure.send_messageA

Create a new unread message in the local Community Mesh store for another agent. Checks the sender's send_message policy and resource approval requirements. Returns blocked=false and message (including message_id/thread_id), or blocked=true with reason and allowed_next_step. Stores/audits a redacted body, digest, and heuristic summary, not the full text; never put secrets in the input. Does not launch/wake the recipient, contact a remote service, or prove the recipient read it. Use agentsecure.reply_message to respond in an existing thread. Example: {"from_agent": "frontend-agent", "to": "backend-agent", "body": "Please review src/app.py."}.

Inputs: to (required), body (required), from_agent (required), type, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool targets a distinct action+resource: inbox counts vs. message records vs. acknowledgement are split across check_messages/list_messages/read_message, and policy inspection is split cleanly into policy.describe (HTTP/secret config), secret.status (single env), and get_policy_hint (Mesh actions). Descriptions actively cross-reference the correct sibling tool for each adjacent use case, leaving little room for misselection.

    Naming Consistency3/5

    All names share the agentsecure. namespace, but the suffix conventions are mixed: dotted resource.action forms (policy.describe, secret.status, http.request) coexist with verb_noun forms (send_message, list_messages, request_approval), and agentsecure.identity has no verb at all. Still readable, but not a predictable single pattern.

    Tool Count5/5

    13 tools is well within a comfortable range and each maps to a distinct facet of the mesh (messaging, approvals, identity, policy, secrets/HTTP, audit). No filler or redundant tools are apparent.

    Completeness4/5

    Messaging (send/list/read/reply/count), approvals (create/read), identity (lookup/register), policy inspection, secret-aware HTTP, and audit retrieval are all covered. Minor gaps remain: no way to cancel or withdraw a pending approval, no message deletion/archival, and no bulk listing of approvals, but agents can work around these.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that lets AI agents call APIs without ever seeing the credentials, using a local encrypted vault and per-secret allowlist policies for HTTP requests and subprocess environment variables.
      1
      AGPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Secrets management MCP server that injects credentials into API requests for AI agents, enforcing policies and logging all activity without exposing raw keys.
      109 npm
      30
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A local-first LLM routing MCP server that keeps sensitive data on your own models, with fail-closed privacy and manager-worker delegation, exposing route and complete tools to any MCP client.
      72 PyPI
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      A local stdio MCP server that enables coding agents to discover credential handles and create scoped action requests with local approval and sanitized output.
      7
      93 npm
      15
      Apache 2.0