devantis-sdk 0.3.7

Python SDK and MCP server for the Devantis AI development platform

devantis-sdk

Python SDK and MCP server for the Devantis AI development platform. Connect Claude CLI, Claude Desktop, or any MCP-compatible client to your Devantis projects with 90 tools for managing source code, tickets, requirements, architecture, designs, AI chat, knowledge graph, deployments, and more.

Installation

pip install devantis-sdk[mcp]

This installs the SDK with MCP server support and WebSocket chat. For the core SDK without MCP:

pip install devantis-sdk

Requirements: Python 3.11+

Setup

1. Login

devantis login

Opens your browser for Keycloak authentication. Saves the token to ~/.devantis_token.json. The token auto-refreshes — you only need to login once.

2. Configure your context

devantis config

Interactive picker for your organisation, project, and application. Saves to ~/.devantis.yaml.

Or set via environment variables:

export DEVANTIS_ORG=my-org
export DEVANTIS_PROJECT=my-project
export DEVANTIS_APP=my-app

3. Connect to services

The SDK defaults to the development platform at https://devantis.dev.encodeit.ro. No extra configuration needed after login + config.

Override the API URL for other environments:

Environment	How it works	Config
Development (default)	Gateway mode — all services behind devantis.dev.encodeit.ro	No config needed
Local (docker-compose)	Each service on its own localhost port	export DEVANTIS_API_URL=""
Docker (inside container)	Docker-internal hostnames	INTERNAL_SERVICE_KEY env var (auto-detected)
Custom	Any other gateway URL	export DEVANTIS_API_URL=https://your-instance.example.com

You can also set the URL permanently in ~/.devantis-mcp.yaml:

api_url: https://devantis.dev.encodeit.ro   # or any custom URL

Priority order: DEVANTIS_API_URL env var > ~/.devantis-mcp.yaml api_url > built-in default

Use as MCP Server (Claude CLI)

Register

claude mcp add devantis -- devantis-mcp

Or with a specific Python path:

claude mcp add devantis -- /path/to/venv/bin/python -m devantis

Verify

claude mcp list
# devantis: ... - Connected

Start using

Open Claude CLI and ask anything:

> List all open tickets

> Search the codebase for authentication

> Create a requirement for user registration

> Ask the AI assistant to implement the login page

> What does the brain know about our API design?

> Show me the kanban board

All 90 tools are available automatically. Claude picks the right tool based on your request.

Chat sessions

The MCP server manages chat sessions with the platform's AI assistant:

• First devantis_chat_send creates a new session automatically
• Subsequent calls reuse the same session (multi-turn conversation)
• When the AI pauses for approval, Claude shows you the question and you approve/deny normally
• Switching context (devantis_switch_context) clears the session

You can also manage sessions explicitly with devantis_chat_session.

Use as MCP Server (Claude Desktop)

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "devantis": {
      "command": "devantis-mcp",
      "env": {
        "DEVANTIS_ORG": "my-org",
        "DEVANTIS_PROJECT": "my-project",
        "DEVANTIS_APP": "my-app"
      }
    }
  }
}

Use as Python SDK

import asyncio
from devantis import DevantisClient

async def main():
    client = await DevantisClient.connect()

    # Source code
    files = await client.source.list()
    content = await client.source.read("src/main.py")
    matches = await client.source.grep("def login", glob="*.py")
    await client.source.write("src/hello.py", "print('hello')")
    await client.source.batch_write([
        {"path": "src/a.py", "content": "# file a"},
        {"path": "src/b.py", "content": "# file b"},
    ])

    # Tickets
    tickets = await client.tickets.list(status="open", priority="high")
    ticket = await client.tickets.create(
        title="Implement OAuth2",
        description="Add OAuth2 login flow",
        feature="authentication",
    )
    await client.tickets.transition(ticket["id"], "start")
    await client.tickets.add_comment(ticket["id"], "Working on this now")

    # Sprints and epics
    sprints = await client.tickets.list_sprints(status="active")
    epics = await client.tickets.list_epics()
    board = await client.tickets.get_board("kanban")
    stats = await client.tickets.get_stats()

    # Requirements
    reqs = await client.requirements.list(status="approved")
    await client.requirements.create(
        title="User Registration",
        description="Users must be able to register...",
        feature="authentication",
    )

    # Architecture and designs
    docs = await client.architecture.list()
    designs = await client.designs.list(file_type="html")

    # Chat with AI assistant
    result = await client.chat.send("How does the auth system work?")
    print(result["content"])

    # If the assistant pauses for approval:
    if result["status"] == "waiting_for_input":
        result = await client.chat.answer(result["session_id"], "Yes, proceed")

    # Knowledge graph (AI brain)
    entities = await client.knowledge_graph.search("auth")
    await client.knowledge_graph.create_entity(
        name="auth-service",
        entity_type="service",
        observations=[{"content": "Uses JWT with 15min expiry", "kind": "fact"}],
    )
    answer = await client.knowledge_graph.reason("How does authentication work?")
    vitals = await client.knowledge_graph.vitals()

    # Cross-entity search
    results = await client.search("authentication")

    # Team management
    members = await client.projects.list_members(level="app")
    me = await client.users.me()

    # Analytics
    usage = await client.analytics.token_usage(view="summary")

    # Billing & Licensing
    plan = await client.billing.get_plan()
    entitlements = await client.billing.get_entitlements()
    credits = await client.billing.get_credits()
    invoices = await client.billing.list_invoices(month="2026-04")
    usage_summary = await client.billing.get_usage()
    seat_cost = await client.billing.get_seat_cost()
    packs = await client.billing.list_credit_packs()
    tax = await client.billing.get_tax_summary()

    # Switch context
    await client.switch_context(app="other-app")

    await client.close()

asyncio.run(main())

Available Services

Service	Access via	Description
source	client.source	File read/write/edit/delete, grep, glob, batch operations
tickets	client.tickets	Full ticket lifecycle, labels, subtasks, links, sprints, epics, boards, charts
requirements	client.requirements	Requirement CRUD, search, feature listing
architecture	client.architecture	Architecture documents and diagrams
designs	client.designs	Design files (HTML, CSS, tokens)
chat	client.chat	AI assistant messaging with pause/resume support
knowledge_graph	client.knowledge_graph	AI brain — entities, observations, relations, reasoning
executors	client.executors	Remote shell commands, Kubernetes deployments
projects	client.projects	Org/project/app management, members, config
analytics	client.analytics	Token usage, cost forecast, alerts
users	client.users	User search and profiles
notifications	client.notifications	Notification channels and subscriptions
billing	client.billing	Invoices, credits, plans, quotas, subscriptions, tax, cost breakdowns
memory	client.memory	Persistent key-value project memory
docs	client.docs	Platform documentation

MCP Tools (90 total)

Source Code (9 tools)

Tool	Description
devantis_read_file	Read a source code file
devantis_write_file	Create or overwrite a file
devantis_edit_file	Targeted find-and-replace with fuzzy matching
devantis_delete_file	Delete a file
devantis_move_file	Move or rename a file
devantis_list_files	List files, optionally by folder
devantis_glob_files	Find files by glob pattern
devantis_grep	Regex search inside file contents
devantis_batch_files	Write/delete/edit up to 20 files at once

Tickets (23 tools)

Tool	Description
devantis_list_tickets	List with filters (status, priority, sprint, epic)
devantis_get_ticket	Full ticket details
devantis_create_ticket	Create a ticket
devantis_update_ticket	Update ticket fields
devantis_delete_ticket	Delete a ticket
devantis_transition_ticket	Move through workflow (start, review, done, block)
devantis_search_tickets	Full-text search
devantis_add_ticket_comment	Add a comment
devantis_list_ticket_comments	List comments
devantis_manage_labels	Label CRUD and ticket assignment
devantis_manage_subtasks	Subtask CRUD
devantis_manage_links	Link tickets (blocks, duplicates, relates_to)
devantis_ticket_watch	Watch/unwatch tickets
devantis_ticket_vote	Vote on tickets
devantis_ticket_timelog	Log time on tickets
devantis_manage_milestones	Milestone CRUD and ticket assignment
devantis_manage_components	Component CRUD and ticket assignment
devantis_manage_filters	Saved filter CRUD and execution
devantis_get_board	Kanban, by-assignee, by-feature, by-priority boards
devantis_get_chart	Burndown, burnup, cumulative flow, velocity charts
devantis_ticket_stats	Aggregate statistics
devantis_manage_sprints	Sprint lifecycle and ticket management
devantis_manage_epics	Epic CRUD and ticket management

Requirements (5 tools)

Tool	Description
devantis_list_requirements	List with filters
devantis_get_requirement	Full requirement details
devantis_create_requirement	Create a requirement
devantis_update_requirement	Update fields
devantis_delete_requirement	Delete a requirement

Architecture (6 tools)

Tool	Description
devantis_list_architecture	List documents and diagrams
devantis_read_architecture	Read document content
devantis_create_architecture	Create document or diagram
devantis_update_architecture	Update content
devantis_delete_architecture	Delete a document
devantis_search_architecture	Search by name

Designs (6 tools)

Tool	Description
devantis_list_designs	List design files (HTML, CSS, tokens)
devantis_read_design	Read file content
devantis_create_design	Create a design file
devantis_update_design	Update content
devantis_delete_design	Delete a file
devantis_search_designs	Search designs

AI Assistant Chat (8 tools)

Tool	Description
devantis_chat_session	Manage active session (set, start, clear, get)
devantis_chat_send	Send message and collect response
devantis_chat_answer	Answer a paused workflow's question
devantis_chat_confirm	Approve/reject a workflow proposal
devantis_chat_history	Get conversation history
devantis_chat_sessions	List recent sessions
devantis_chat_stop	Cancel running workflow
devantis_chat_delete	Delete a session

Knowledge Graph / AI Brain (12 tools)

Tool	Description
devantis_kg_search	Search entities and observations
devantis_kg_get_entity	Get entity with all observations
devantis_kg_add	Create entity with observations
devantis_kg_add_observation	Add observation to existing entity
devantis_kg_remove	Delete entity, observation, or relation
devantis_kg_relations	Manage entity relations
devantis_kg_reason	LLM reasoning over stored knowledge
devantis_kg_stats	Graph statistics
devantis_kg_vitals	Brain health and intelligence score
devantis_kg_impact	Impact analysis (what depends on this?)
devantis_kg_confirm_observation	Mark observation as still valid
devantis_kg_dependencies	Recursive dependency traversal

Executors and Deployment (3 tools)

Tool	Description
devantis_executor_shell	Run shell commands on remote agents
devantis_deploy_k8s	Kubernetes operations via MCP
devantis_list_executors	List executor agents and status

Analytics (2 tools)

Tool	Description
devantis_token_usage	Token usage and cost analytics
devantis_cost_forecast	Cost predictions and spending alerts

Users and Team (4 tools)

Tool	Description
devantis_users_search	Find users by name or email
devantis_users_me	Current user profile
devantis_list_members	List members at org/project/app level
devantis_manage_members	Add, update, or remove members

Billing & Licensing (1 tool, 27 actions)

Tool	Description
devantis_billing	Unified billing tool with action parameter

Plan & Quotas: get_plan, list_plans, get_entitlements, get_usage, get_overage_rates Invoices: list_invoices, get_invoice, upcoming_invoice, retry_invoice Credits: get_credits, list_transactions, list_credit_packs, purchase_credits, allocate_credits Subscription: cancel_subscription, reactivate_subscription Payment Methods: list_payment_methods, remove_payment_method, set_default_payment_method Tax: get_tax_summary, list_tax_ids, add_tax_id, remove_tax_id, get_tax_types Cost Breakdown: get_seat_cost, get_executor_cost, get_k8s_cost, get_registry_cost

Platform (11 tools)

Tool	Description
devantis_search	Cross-entity parallel search
devantis_memory	Persistent project memory
devantis_switch_context	Switch org/project/app
devantis_list_projects	List orgs, projects, or apps
devantis_get_config	Get app configuration
devantis_update_config	Update configuration
devantis_manage_notifications	Notification channels and subscriptions
devantis_bulk_tickets	Batch ticket operations
devantis_list_docs	List documentation pages
devantis_read_doc	Read a documentation page
devantis_search_docs	Search documentation

Authentication Modes

Mode	Use case	Configuration
User token	Local dev, Claude CLI	devantis login (saves to ~/.devantis_token.json)
Internal key	Docker containers, workers	INTERNAL_SERVICE_KEY env var
Service account	Server-to-server	Keycloak client credentials

Auto-detected based on environment. No manual selection needed.

Links

• Platform: devantis.dev
• Source: github.com/encode-it-srl/devantis

License

MIT