Agent Identity Management MCP Server

OpenA2A AIM (Agent Identity Management)

OpenA2A: CLI · HackMyAgent · Secretless · AIM · Browser Guard · DVAA

Website · AIM Cloud · Discord

Cryptographic identity, capability authorization, and audit trails for AI agents.

Quick start

pip install "aim-sdk[rich]"
aim-sdk login                              # OAuth to aim.opena2a.org
aim-sdk login --url http://localhost:8080  # or to your self-hosted AIM

The [rich] extra is optional and formats the output shown below; plain pip install aim-sdk works and prints the same fields in a panel. Then register an agent, in a Python session, with the capability it holds. What secure() prints, trimmed (full output):

from aim_sdk import secure
agent = secure("my-first-agent", capabilities=["db:read"])

  ○ Agent Type: using default 'ai_agent'

[OK] Agent registered: my-first-agent
  ...
  Status: ○ pending  Trust: 59%
  Capabilities: db:read

aim-sdk login prints a code you approve on your dashboard's /device page; the PyPI release does not yet (self-hosted sign-in, #789). secure() generates an Ed25519 keypair and stores credentials at ~/.aim/.

The agent starts pending until an administrator verifies it under Agents in the dashboard. On a new organization, which starts in monitoring mode, a pending agent's call runs and raises an Unverified Agent Action (Monitoring Mode) alert. On a strict-mode organization every call is refused with Agent not verified - all actions denied until then.

Once it is verified, protect a function with that capability and call it:

customers = {42: {"name": "Ada Lovelace", "plan": "team"}}

@agent.perform_action(capability="db:read")
def get_customer(customer_id):
    return customers[customer_id]

get_customer(42)

@perform_action signs each call, has AIM's 5-step Fine-Grained Authorization engine check it, first against granted capabilities and security policies, and logs the outcome.

The refusal below needs strict mode (dashboard: Security, then Policies, Global Enforcement Mode: Strict); in the default monitoring mode, db:write runs and deletes the record.

Now call something the agent was not granted. my-first-agent holds db:read only:

@agent.perform_action(capability="db:write")
def delete_customer(customer_id):
    del customers[customer_id]

delete_customer(42)

AIM refuses it before the function body runs. What the call prints, trimmed (full output):

Capability 'db:write' pending admin approval (strict mode)
aim_sdk.exceptions.ActionDeniedError: AIM denied 'db:write': Capability violation blocked by security policy 'Capability Violation Detection': Agent does not have permission for capability 'db:write' (allowed: [db:read]). The action was blocked and not executed. AIM denies an action after applying your organization's enforcement mode (currently strict), so a denial blocks in every mode -- monitoring mode governs verifications AIM could not answer, not ones it refused. To permit this capability, grant it to this agent in the AIM dashboard under Agents. If the agent should not be denied at all, check its status there: an agent marked compromised, suspended or unverified is refused regardless of its capabilities.

The decorator files a request for db:write, and the agent's audit log records the denial with the same reason. On a stack started from the quickstart defaults, the reason names the built-in default_policy instead of 'Capability Violation Detection'.

The SDK built from this repository printed the registration capture, and the release on PyPI printed the refusal; the release on PyPI prints ✓ where this repository's build prints [OK], and adds ✓ Registered db:write (medium) after the refusal's first line.

The trust score is calculated at registration and recalculated when a manager verifies, suspends or reactivates the agent, grants or revokes a capability, or calls POST /api/v1/agents/:id/trust-score/recalculate, and every hour by default by the trust re-evaluation job (TRUST_REEVALUATION_INTERVAL). What a verification request does to it: Trust-gated capabilities.

The same one-line shape works in Java; TypeScript has no secure() call (local mode).

What you can do

• Protect an agent's calls in Python: Quick start.
• Protect them in Java: Java quick start.
• Check capabilities and keep an audit log with no server: local mode in TypeScript.
• Register an agent from an app or the terminal: Register an agent.
• Track what an agent does: Audit agent actions.
• Restrict what an agent can do: Enforce capabilities.
• Add identity to your agent framework: Embed in an app.
• Govern many agents: Fleet governance.
• Gate privileged actions, attest MCP servers and forward audit logs to Splunk: Server features.

All 11 jobs: docs/USE-CASES.md.

Deployment

Mode	When	Includes
AIM Cloud	Managed	Hosted at aim.opena2a.org/get-started. Python and Java SDKs work out of the box.
Self-hosted	Your infrastructure	PostgreSQL audit, REST API, dashboard, OAuth, 5-step FGA, 9-factor trust score, MCP attestation, PAM, audit log forwarding to Splunk.
Local-only	One machine, no server	TypeScript SDK + opena2a CLI. 8-factor local trust score. Local mode is in the TypeScript SDK only.

Local only mode keeps its own event format in ~/.opena2a/aim-core/audit.jsonl, separate from the server's audit log. It includes an Ed25519 keypair and YAML capability policies.

SDKs

SDK	Install	Mode	API
Python	pip install aim-sdk	Server	secure("name") + @perform_action
Java	cd sdk/java && mvn install (from source)	Server	AIMClient.secure("name") + @SecureAction
TypeScript	npm install @opena2a/aim-core	Local	new AIMCore({ agentName })

Each SDK's README: Python, Java, TypeScript; examples for all three are in examples/. The SDKs send requests only to the AIM server you signed in to; the causal-denial telemetry the Python and TypeScript SDK READMEs describe is opt-in and off until you configure it; the Java SDK has none.

Java

AIMClient agent = AIMClient.secure("my-first-agent");

@SecureAction(capability = "db:read", resource = "users_table")
public User getCustomer(String customerId) {
    return userRepository.findById(customerId);
}

AspectJ wraps each @SecureAction invocation with the same Ed25519 signing and audit trail.

Install AIM (self-hosted)

curl -sSLO https://raw.githubusercontent.com/opena2a-org/agent-identity-management/main/scripts/quickstart.sh
bash quickstart.sh

It needs Docker running, openssl and curl, and writes the compose file and a .env of generated secrets to ./aim. Brings up aim-server, aim-dashboard, PostgreSQL, and Redis. Dashboard at localhost:3000, API at localhost:8080. Login credentials print at the end of the run.

The script runs from main and starts the aim-server and aim-dashboard images at their latest tags; nothing on this path is pinned or verified, so read the script and the compose file first.

Image tags, building from source, observability and the first administrator on other setups: docs/DEPLOYMENT.md. Production on Azure, GCP or AWS: infrastructure/DEPLOYMENT.md.

Documentation

• See it work: the audit log behind the two calls above, where to grant db:write, and the Quick start's notes in full.
• Server features, Deployment, Verifying the @opena2a/aim-core package, Use cases, Demos and the A/B recording.
• opena2a CLI commands: harden configs and monitor runtime events, with no server.
• SDK quickstart tutorial, MCP registration, the documentation site, Research.
• Roadmap
• Contributing: the dev loop and pull requests. Report security issues to info@opena2a.org; SECURITY.md says what to expect.

License

Apache-2.0. See LICENSE.