Skip to content

Upgrade keycardai-mcp-fastmcp to FastMCP 3.0#89

Merged
Larry-Osakwe merged 2 commits intomainfrom
larry/fastmcp-3.0
Apr 1, 2026
Merged

Upgrade keycardai-mcp-fastmcp to FastMCP 3.0#89
Larry-Osakwe merged 2 commits intomainfrom
larry/fastmcp-3.0

Conversation

@Larry-Osakwe
Copy link
Copy Markdown
Contributor

Summary

  • Upgrades fastmcp dependency from >=2.14.0,<3.0.0 to >=3.0.0
  • Migrates ctx.get_state() / ctx.set_state() to async (FastMCP 3.0 breaking change)
  • Uses serializable=False for AccessContext storage since it's a non-serializable Python class used within a single request
  • Updates all examples, documentation, and tests

Breaking changes for users

  • ctx.get_state("keycardai")await ctx.get_state("keycardai") in tool functions
  • Tool functions using @grant must be async def

Test plan

  • All 51 mcp-fastmcp tests pass
  • All 623 mcp tests pass
  • Verified all 4 FastMCP import paths work unchanged in 3.2.0
  • Verified set_state(serializable=False) works for class instances
  • Verified decorator stacking (@mcp.tool() + @grant) works in 3.0
  • End-to-end test with a live Keycard zone

Linear: AGE-101, AGE-102, AGE-103, AGE-104

🤖 Generated with Claude Code

Upgrade keycardai-mcp-fastmcp from fastmcp>=2.14.0,<3.0.0 to fastmcp>=3.0.0.

Key changes:
- ctx.get_state()/ctx.set_state() are now async (FastMCP 3.0 breaking change)
- grant decorator uses await ctx.set_state(..., serializable=False)
- All examples, docs, and tests updated for async state access
- Test mocks updated to use async functions for get_state/set_state
@github-actions
Copy link
Copy Markdown

📦 Release Preview

This analysis shows the expected release impact:

📈 Expected Version Changes

keycardai-mcp-fastmcp: 0.19.0 → 0.20.0 (MINOR)

📋 Package Details

[
  {
    "package_name": "keycardai-mcp-fastmcp",
    "package_dir": "packages/mcp-fastmcp",
    "has_changes": true,
    "current_version": "0.19.0",
    "next_version": "0.20.0",
    "increment": "MINOR"
  }
]

📝 Changelog Preview

Changelog for keycardai:
## Unreleased

## 0.2.0-keycardai (2025-09-10)

## 0.1.0-keycardai (2025-09-07)


- feat(keycardai): initial release
Changelog for keycardai-mcp:
## Unreleased

## 0.21.0-keycardai-mcp (2026-03-06)


- build(keycardai-mcp): bump keycardai-oauth dependency to >=0.7.0
- refactor(keycardai-mcp)!: optimize error formatting in token exchange chain
- Restructure error dicts to remove redundancy and improve readability.
Key renames: error->message, error_code->code, error_description->description,
resource_errors->resources. Only include raw_error for non-OAuth exceptions.
- BREAKING CHANGE: Error dict keys renamed: error->message, error_code->code, error_description->description. The get_errors() output key resource_errors is now resources.

## 0.20.1-keycardai-mcp (2026-02-06)


- fix(keycardai-mcp): return prm for resources dynamically

## 0.20.0-keycardai-mcp (2026-01-07)


- feat(keycardai-mcp): Adds PydanticAI integration for MCP frameworks
- - Adds PaydanticAI adapter to client integrations directory
- Support for PydanticAI agents with secure MCP tool access
- Follows established pattern with LangChain and OpenAI integrations
- Adds tests for PydanticAI integration imports

## 0.19.0-keycardai-mcp (2026-01-07)


- feat(keycardai-mcp): Add greater control over OAuth metadata location
- - Refactors `auth_metadata_mount` into it's component parts
- Exposes mounts for individual metadata
- Allows the user to specify exactly where their OAuth metadata is
exposed
- NOTE: This is only for advanced use cases where you know you need
something non-standard. Otherwise, follow the OAuth spec.

## 0.18.0-keycardai-mcp (2025-12-04)


- feat(keycardai-mcp): add CrewAI integration for agent frameworks
- - Add CrewAI adapter to client integrations directory
- Support for CrewAI agents with secure MCP tool access
- No token passing - agents never receive raw API tokens
- Fresh token fetched per API call through Keycard
- Follows established pattern with LangChain and OpenAI integrations
- Deleted separate packages/agents package (not needed)
- Added optional dependencies: crewai and agents extras
- Added tests for CrewAI integration imports

## 0.17.0-keycardai-mcp (2025-11-18)


- feat(keycardai-mcp): session callback notification
- feat(keycardai-mcp): session lifecycle management

## 0.16.0-keycardai-mcp (2025-11-17)


- feat(keycardai-mcp): headless clients
- feat(keycardai-mcp): update oauth deps
- feat(keycardai-mcp): client implementation

## 0.15.0-keycardai-mcp (2025-11-07)


- feat(keycardai-mcp): enable web token eks env

## 0.14.0-keycardai-mcp (2025-11-06)


- feat(keycardai-mcp): configure mcp url via env

## 0.13.0-keycardai-mcp (2025-11-05)


- feat(keycardai-mcp): zone settings via env

## 0.12.0-keycardai-mcp (2025-11-05)


- feat(keycardai-mcp): automatic app cred discovery
- feat(keycardai-mcp): default eks env

## 0.11.0-keycardai-mcp (2025-10-29)


- feat(keycardai-mcp): release latest version
- Release current version of workload identity implementation

## 0.10.0-keycardai-mcp (2025-10-27)


- feat(keycardai-mcp): cach the application credentials
- feat(keycardai-mcp): app credential grant flow

## 0.9.0-keycardai-mcp (2025-10-20)


- refactor(keycardai-mcp): align credential names
- feat(keycardai-mcp): eks workload identity support
- feat(keycardai-mcp): add application authentication

## 0.8.1-keycardai-mcp (2025-10-10)


- fix(keycardai-mcp): wrong base url in auth metadata

## 0.8.0-keycardai-mcp (2025-10-07)


- refactor(keycardai-mcp): improve error messages
- refactor(keycardai-mcp): improves the error messages to provide useful debug information

## 0.7.1-keycardai-mcp (2025-09-29)


- fix(keycardai-mcp): set audience for client assertions

## 0.7.0-keycardai-mcp (2025-09-27)


- feat(keycardai-mcp): lowlevel support for RequestContext

## 0.6.0-keycardai-mcp (2025-09-23)


- feat(keycardai-mcp): enable custom middleware injection

## 0.5.1-keycardai-mcp (2025-09-22)


- fix(keycardai-mcp): support x-forwarded-port header

## 0.5.0-keycardai-mcp (2025-09-22)


- feat(keycardai-mcp): dcr can be toggled on/off
- feat(keycardai-mcp): private key jwt support with global key
- feat(keycardai-mcp): grant decorator exception handling
- feat(keycardai-mcp): private key manager protocol

## 0.4.1-keycardai-mcp (2025-09-18)


- fix(keycardai-mcp): support both sync and async tool calls

## 0.4.0-keycardai-mcp (2025-09-18)


- feat(keycardai-mcp): default domain handling

## 0.3.1-keycardai-mcp (2025-09-17)


- fix(keycardai-mcp): check audience when configured

## 0.3.0-keycardai-mcp (2025-09-16)


- feat(keycardai-mcp): multi-zone mcp routing
- feat(keycardai-mcp): advanced server handlers
- feat(keycardai-mcp): auth provider implementation

## 0.1.0-keycardai-mcp (2025-09-10)
Changelog for keycardai-oauth:
## Unreleased

## 0.7.0-keycardai-oauth (2026-03-06)


- fix(keycardai-oauth): update test to expect OAuthProtocolError for structured error bodies
- feat(keycardai-oauth)!: detailed error reporting
- BREAKING CHANGE: Token exchange HTTP 4xx errors with structured JSON bodies now raise OAuthProtocolError instead of OAuthHttpError. Callers catching OAuthHttpError for these responses must update to catch OAuthProtocolError.

## 0.6.0-keycardai-oauth (2025-11-17)


- feat(keycardai-oauth): client metadata updates

## 0.5.0-keycardai-oauth (2025-09-22)


- feat(keycardai-oauth): client assertion support
- feat(keycardai-oauth): JWKS type support

## 0.4.1-keycardai-oauth (2025-09-17)


- fix(keycardai-oauth): audience checks

## 0.4.0-keycardai-oauth (2025-09-16)


- feat(keycardai-oauth): multi-zone authentication strategy
- feat(keycardai-oauth): jwt capabilities

## 0.2.0-keycardai-oauth (2025-09-10)


- feat(keycardai-oauth): remove the impersonation logic

## 0.1.0-keycardai-oauth (2025-09-07)


- feat(keycardai-oauth): initial release
Changelog for keycardai-agents:
## Unreleased

## 0.1.1-keycardai-agents (2026-01-07)
Changelog for keycardai-mcp-fastmcp:
## Unreleased


- feat(keycardai-mcp-fastmcp): upgrade to FastMCP 3.0
- Upgrade keycardai-mcp-fastmcp from fastmcp>=2.14.0,<3.0.0 to fastmcp>=3.0.0.
- Key changes:
- ctx.get_state()/ctx.set_state() are now async (FastMCP 3.0 breaking change)
- grant decorator uses await ctx.set_state(..., serializable=False)
- All examples, docs, and tests updated for async state access
- Test mocks updated to use async functions for get_state/set_state

## 0.19.0-keycardai-mcp-fastmcp (2026-03-06)


- refactor(keycardai-mcp-fastmcp)!: optimize error formatting in token exchange chain
- Restructure error dicts to remove redundancy and improve readability.
Key renames: error->message, error_code->code, error_description->description,
resource_errors->resources. Only include raw_error for non-OAuth exceptions.
- BREAKING CHANGE: Error dict keys renamed: error->message, error_code->code, error_description->description. The get_errors() output key resource_errors is now resources.

## 0.18.1-keycardai-mcp-fastmcp (2025-11-23)


- fix(keycardai-mcp-fastmcp): include subject in debug

## 0.18.0-keycardai-mcp-fastmcp (2025-11-20)


- feat(keycardai-mcp-fastmcp): debug information for exchange

## 0.17.0-keycardai-mcp-fastmcp (2025-11-17)


- feat(keycardai-mcp-fastmcp): update oauth deps

## 0.16.0-keycardai-mcp-fastmcp (2025-11-07)


- feat(keycardai-mcp-fastmcp): enable web token eks env

## 0.15.0-keycardai-mcp-fastmcp (2025-11-06)


- feat(keycardai-mcp-fastmcp): configure mcp url via env

## 0.14.0-keycardai-mcp-fastmcp (2025-11-05)


- feat(keycardai-mcp-fastmcp): configure zone setting via env

## 0.13.0-keycardai-mcp-fastmcp (2025-11-05)


- feat(keycardai-mcp-fastmcp): automatic app cred discovery

## 0.12.0-keycardai-mcp-fastmcp (2025-10-29)


- feat(keycardai-mcp-fastmcp): support fastmcp 2.13

## 0.11.0-keycardai-mcp-fastmcp (2025-10-29)


- feat(keycardai-mcp-fastmcp): keycardai mcp dep update
- Reverts the eks workload identity changes

## 0.10.0-keycardai-mcp-fastmcp (2025-10-27)


- feat(keycardai-mcp-fastmcp): use application cred cache

## 0.9.0-keycardai-mcp-fastmcp (2025-10-20)


- feat(keycardai-mcp-fastmcp): EKS workload identity

## 0.8.1-keycardai-mcp-fastmcp (2025-10-07)


- refactor(keycardai-mcp-fastmcp): improve error message with debug context

## 0.8.0-keycardai-mcp-fastmcp (2025-10-01)


- feat(keycardai-mcp-fastmcp): ability to mock internal access context for testing

## 0.7.0-keycardai-mcp-fastmcp (2025-09-27)


- refactor(keycardai-mcp-fastmcp): remove the error codes from AccessContext

## 0.6.0-keycardai-mcp-fastmcp (2025-09-22)


- feat(keycardai-mcp-fastmcp): unify exceptions with keycardai-mcp package

## 0.5.0-keycardai-mcp-fastmcp (2025-09-21)


- feat(keycardai-mcp-fastmcp): client factory and base url update

## 0.4.1-keycardai-mcp-fastmcp (2025-09-19)


- fix(keycardai-mcp-fastmcp): lock the oauth dependency

## 0.4.0-keycardai-mcp-fastmcp (2025-09-18)


- feat(keycardai-mcp-fastmcp): refactor API for the provider

## 0.3.0-keycardai-mcp-fastmcp (2025-09-15)


- feat(keycardai-mcp-fastmcp): unify client arguments

## 0.2.0-keycardai-mcp-fastmcp (2025-09-10)


- fix(keycardai-mcp-fastmcp): pin fastmcp for compatibiity
- feat(keycardai-mcp-fastmcp): allowed to override the client

## 0.1.0-keycardai-mcp-fastmcp (2025-09-07)

This comment was automatically generated by the release preview workflow.

The example pyproject.toml files still pinned fastmcp<3.0.0, preventing
them from resolving against the updated SDK.
@github-actions
Copy link
Copy Markdown

📦 Release Preview

This analysis shows the expected release impact:

📈 Expected Version Changes

keycardai-mcp-fastmcp: 0.19.0 → 0.20.0 (MINOR)

📋 Package Details

[
  {
    "package_name": "keycardai-mcp-fastmcp",
    "package_dir": "packages/mcp-fastmcp",
    "has_changes": true,
    "current_version": "0.19.0",
    "next_version": "0.20.0",
    "increment": "MINOR"
  }
]

📝 Changelog Preview

Changelog for keycardai:
## Unreleased

## 0.2.0-keycardai (2025-09-10)

## 0.1.0-keycardai (2025-09-07)


- feat(keycardai): initial release
Changelog for keycardai-mcp:
## Unreleased

## 0.21.0-keycardai-mcp (2026-03-06)


- build(keycardai-mcp): bump keycardai-oauth dependency to >=0.7.0
- refactor(keycardai-mcp)!: optimize error formatting in token exchange chain
- Restructure error dicts to remove redundancy and improve readability.
Key renames: error->message, error_code->code, error_description->description,
resource_errors->resources. Only include raw_error for non-OAuth exceptions.
- BREAKING CHANGE: Error dict keys renamed: error->message, error_code->code, error_description->description. The get_errors() output key resource_errors is now resources.

## 0.20.1-keycardai-mcp (2026-02-06)


- fix(keycardai-mcp): return prm for resources dynamically

## 0.20.0-keycardai-mcp (2026-01-07)


- feat(keycardai-mcp): Adds PydanticAI integration for MCP frameworks
- - Adds PaydanticAI adapter to client integrations directory
- Support for PydanticAI agents with secure MCP tool access
- Follows established pattern with LangChain and OpenAI integrations
- Adds tests for PydanticAI integration imports

## 0.19.0-keycardai-mcp (2026-01-07)


- feat(keycardai-mcp): Add greater control over OAuth metadata location
- - Refactors `auth_metadata_mount` into it's component parts
- Exposes mounts for individual metadata
- Allows the user to specify exactly where their OAuth metadata is
exposed
- NOTE: This is only for advanced use cases where you know you need
something non-standard. Otherwise, follow the OAuth spec.

## 0.18.0-keycardai-mcp (2025-12-04)


- feat(keycardai-mcp): add CrewAI integration for agent frameworks
- - Add CrewAI adapter to client integrations directory
- Support for CrewAI agents with secure MCP tool access
- No token passing - agents never receive raw API tokens
- Fresh token fetched per API call through Keycard
- Follows established pattern with LangChain and OpenAI integrations
- Deleted separate packages/agents package (not needed)
- Added optional dependencies: crewai and agents extras
- Added tests for CrewAI integration imports

## 0.17.0-keycardai-mcp (2025-11-18)


- feat(keycardai-mcp): session callback notification
- feat(keycardai-mcp): session lifecycle management

## 0.16.0-keycardai-mcp (2025-11-17)


- feat(keycardai-mcp): headless clients
- feat(keycardai-mcp): update oauth deps
- feat(keycardai-mcp): client implementation

## 0.15.0-keycardai-mcp (2025-11-07)


- feat(keycardai-mcp): enable web token eks env

## 0.14.0-keycardai-mcp (2025-11-06)


- feat(keycardai-mcp): configure mcp url via env

## 0.13.0-keycardai-mcp (2025-11-05)


- feat(keycardai-mcp): zone settings via env

## 0.12.0-keycardai-mcp (2025-11-05)


- feat(keycardai-mcp): automatic app cred discovery
- feat(keycardai-mcp): default eks env

## 0.11.0-keycardai-mcp (2025-10-29)


- feat(keycardai-mcp): release latest version
- Release current version of workload identity implementation

## 0.10.0-keycardai-mcp (2025-10-27)


- feat(keycardai-mcp): cach the application credentials
- feat(keycardai-mcp): app credential grant flow

## 0.9.0-keycardai-mcp (2025-10-20)


- refactor(keycardai-mcp): align credential names
- feat(keycardai-mcp): eks workload identity support
- feat(keycardai-mcp): add application authentication

## 0.8.1-keycardai-mcp (2025-10-10)


- fix(keycardai-mcp): wrong base url in auth metadata

## 0.8.0-keycardai-mcp (2025-10-07)


- refactor(keycardai-mcp): improve error messages
- refactor(keycardai-mcp): improves the error messages to provide useful debug information

## 0.7.1-keycardai-mcp (2025-09-29)


- fix(keycardai-mcp): set audience for client assertions

## 0.7.0-keycardai-mcp (2025-09-27)


- feat(keycardai-mcp): lowlevel support for RequestContext

## 0.6.0-keycardai-mcp (2025-09-23)


- feat(keycardai-mcp): enable custom middleware injection

## 0.5.1-keycardai-mcp (2025-09-22)


- fix(keycardai-mcp): support x-forwarded-port header

## 0.5.0-keycardai-mcp (2025-09-22)


- feat(keycardai-mcp): dcr can be toggled on/off
- feat(keycardai-mcp): private key jwt support with global key
- feat(keycardai-mcp): grant decorator exception handling
- feat(keycardai-mcp): private key manager protocol

## 0.4.1-keycardai-mcp (2025-09-18)


- fix(keycardai-mcp): support both sync and async tool calls

## 0.4.0-keycardai-mcp (2025-09-18)


- feat(keycardai-mcp): default domain handling

## 0.3.1-keycardai-mcp (2025-09-17)


- fix(keycardai-mcp): check audience when configured

## 0.3.0-keycardai-mcp (2025-09-16)


- feat(keycardai-mcp): multi-zone mcp routing
- feat(keycardai-mcp): advanced server handlers
- feat(keycardai-mcp): auth provider implementation

## 0.1.0-keycardai-mcp (2025-09-10)
Changelog for keycardai-oauth:
## Unreleased

## 0.7.0-keycardai-oauth (2026-03-06)


- fix(keycardai-oauth): update test to expect OAuthProtocolError for structured error bodies
- feat(keycardai-oauth)!: detailed error reporting
- BREAKING CHANGE: Token exchange HTTP 4xx errors with structured JSON bodies now raise OAuthProtocolError instead of OAuthHttpError. Callers catching OAuthHttpError for these responses must update to catch OAuthProtocolError.

## 0.6.0-keycardai-oauth (2025-11-17)


- feat(keycardai-oauth): client metadata updates

## 0.5.0-keycardai-oauth (2025-09-22)


- feat(keycardai-oauth): client assertion support
- feat(keycardai-oauth): JWKS type support

## 0.4.1-keycardai-oauth (2025-09-17)


- fix(keycardai-oauth): audience checks

## 0.4.0-keycardai-oauth (2025-09-16)


- feat(keycardai-oauth): multi-zone authentication strategy
- feat(keycardai-oauth): jwt capabilities

## 0.2.0-keycardai-oauth (2025-09-10)


- feat(keycardai-oauth): remove the impersonation logic

## 0.1.0-keycardai-oauth (2025-09-07)


- feat(keycardai-oauth): initial release
Changelog for keycardai-agents:
## Unreleased

## 0.1.1-keycardai-agents (2026-01-07)
Changelog for keycardai-mcp-fastmcp:
## Unreleased


- feat(keycardai-mcp-fastmcp): upgrade to FastMCP 3.0
- Upgrade keycardai-mcp-fastmcp from fastmcp>=2.14.0,<3.0.0 to fastmcp>=3.0.0.
- Key changes:
- ctx.get_state()/ctx.set_state() are now async (FastMCP 3.0 breaking change)
- grant decorator uses await ctx.set_state(..., serializable=False)
- All examples, docs, and tests updated for async state access
- Test mocks updated to use async functions for get_state/set_state

## 0.19.0-keycardai-mcp-fastmcp (2026-03-06)


- refactor(keycardai-mcp-fastmcp)!: optimize error formatting in token exchange chain
- Restructure error dicts to remove redundancy and improve readability.
Key renames: error->message, error_code->code, error_description->description,
resource_errors->resources. Only include raw_error for non-OAuth exceptions.
- BREAKING CHANGE: Error dict keys renamed: error->message, error_code->code, error_description->description. The get_errors() output key resource_errors is now resources.

## 0.18.1-keycardai-mcp-fastmcp (2025-11-23)


- fix(keycardai-mcp-fastmcp): include subject in debug

## 0.18.0-keycardai-mcp-fastmcp (2025-11-20)


- feat(keycardai-mcp-fastmcp): debug information for exchange

## 0.17.0-keycardai-mcp-fastmcp (2025-11-17)


- feat(keycardai-mcp-fastmcp): update oauth deps

## 0.16.0-keycardai-mcp-fastmcp (2025-11-07)


- feat(keycardai-mcp-fastmcp): enable web token eks env

## 0.15.0-keycardai-mcp-fastmcp (2025-11-06)


- feat(keycardai-mcp-fastmcp): configure mcp url via env

## 0.14.0-keycardai-mcp-fastmcp (2025-11-05)


- feat(keycardai-mcp-fastmcp): configure zone setting via env

## 0.13.0-keycardai-mcp-fastmcp (2025-11-05)


- feat(keycardai-mcp-fastmcp): automatic app cred discovery

## 0.12.0-keycardai-mcp-fastmcp (2025-10-29)


- feat(keycardai-mcp-fastmcp): support fastmcp 2.13

## 0.11.0-keycardai-mcp-fastmcp (2025-10-29)


- feat(keycardai-mcp-fastmcp): keycardai mcp dep update
- Reverts the eks workload identity changes

## 0.10.0-keycardai-mcp-fastmcp (2025-10-27)


- feat(keycardai-mcp-fastmcp): use application cred cache

## 0.9.0-keycardai-mcp-fastmcp (2025-10-20)


- feat(keycardai-mcp-fastmcp): EKS workload identity

## 0.8.1-keycardai-mcp-fastmcp (2025-10-07)


- refactor(keycardai-mcp-fastmcp): improve error message with debug context

## 0.8.0-keycardai-mcp-fastmcp (2025-10-01)


- feat(keycardai-mcp-fastmcp): ability to mock internal access context for testing

## 0.7.0-keycardai-mcp-fastmcp (2025-09-27)


- refactor(keycardai-mcp-fastmcp): remove the error codes from AccessContext

## 0.6.0-keycardai-mcp-fastmcp (2025-09-22)


- feat(keycardai-mcp-fastmcp): unify exceptions with keycardai-mcp package

## 0.5.0-keycardai-mcp-fastmcp (2025-09-21)


- feat(keycardai-mcp-fastmcp): client factory and base url update

## 0.4.1-keycardai-mcp-fastmcp (2025-09-19)


- fix(keycardai-mcp-fastmcp): lock the oauth dependency

## 0.4.0-keycardai-mcp-fastmcp (2025-09-18)


- feat(keycardai-mcp-fastmcp): refactor API for the provider

## 0.3.0-keycardai-mcp-fastmcp (2025-09-15)


- feat(keycardai-mcp-fastmcp): unify client arguments

## 0.2.0-keycardai-mcp-fastmcp (2025-09-10)


- fix(keycardai-mcp-fastmcp): pin fastmcp for compatibiity
- feat(keycardai-mcp-fastmcp): allowed to override the client

## 0.1.0-keycardai-mcp-fastmcp (2025-09-07)

This comment was automatically generated by the release preview workflow.

@Larry-Osakwe Larry-Osakwe merged commit 7453bca into main Apr 1, 2026
6 checks passed
@Larry-Osakwe Larry-Osakwe deleted the larry/fastmcp-3.0 branch April 1, 2026 20:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants