Architecture: Service API authorization design (Option 4)#27
Closed
joanreyero wants to merge 4 commits intomainfrom
Closed
Architecture: Service API authorization design (Option 4)#27joanreyero wants to merge 4 commits intomainfrom
joanreyero wants to merge 4 commits intomainfrom
Conversation
Design document for Eric's review covering how the MCP server will authorize access to service APIs (member onboarding, LFX Lens) using the V2 access-check endpoint. Includes sequence diagrams, tool inventory, access rules, and open questions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Joan Reyero <joan@reyero.io>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a proposal architecture document describing how the LFX MCP Server should enforce per-user, per-project authorization when proxying to internal service APIs (Member Onboarding, LFX Lens) that only support API-key authentication.
Changes:
- Documents “Option 4” flow: slug→UUID resolution + V2 access-check before calling service APIs with API keys.
- Adds Mermaid sequence diagrams (happy path, denied, stdio/local dev) and an access-check contract section.
- Includes per-service access rules, initial onboarding tool inventory, configuration/env vars, and open questions for review.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+133
to
+142
| participant Svc as Service API | ||
|
|
||
| User->>MCP: tools/call (onboarding_list_memberships) | ||
|
|
||
| Note over MCP: No TokenInfo present (stdio mode)<br/>→ Skip JWT, scope, and access checks | ||
|
|
||
| MCP->>Svc: GET /member-onboarding/pytorch/memberships<br/>Authorization: Bearer <api-key> | ||
| Svc-->>MCP: {memberships: [...]} | ||
|
|
||
| MCP-->>User: CallToolResult {content: [{text: ...}]} |
|
|
||
| Note over MCP: Access denied — do NOT call service API | ||
|
|
||
| MCP-->>User: CallToolResult {isError: true,<br/>content: "You do not have writer access to project 'pytorch'"} |
| MCP->>V2Query: Resolve slug → UUID | ||
| V2Query-->>MCP: {uid: "abc-123"} | ||
|
|
||
| MCP->>V2AC: POST /access-check?v=1<br/>{"requests": ["project:abc-123#writer"]} |
| V2Auth-->>MCP: <v2-token> | ||
|
|
||
| MCP->>V2Query: GET /query?type=project&slug=pytorch<br/>Bearer: <v2-token> | ||
| V2Query-->>MCP: {uid: "abc-123", slug: "pytorch", ...} |
| | **Owner** | — | Highest access, inherits from parent projects | | ||
| | **Writer** | — | Can write to most attributes, inherits from parent projects | | ||
| | **Auditor** | — | Read access to everything + subordinate objects | | ||
| | **Viewer** | Auditor (implicit) | Can see object exists + key properties, no inheritance to subordinates | |
Comment on lines
+293
to
+309
| | MCP Tool Name | Backend Endpoint | MCP Scope | V2 Relation | Description | | ||
| |---------------|-----------------|-----------|-------------|-------------| | ||
| | `onboarding_list_memberships` | `GET /{slug}/memberships` | `read:all` | `writer` | List memberships with agent action/todo counts | | ||
| | `onboarding_get_membership` | `GET /{slug}/memberships/{id}` | `read:all` | `writer` | Get full membership detail with per-agent data | | ||
| | `onboarding_list_agent_configs` | `GET /{project}/agents/configs` | `read:all` | `writer` | List all agent configurations for a project | | ||
| | `onboarding_get_agent_rules` | `GET /{project}/agents/{agent_id}/rules` | `read:all` | `writer` | Get rules for a specific agent | | ||
| | `onboarding_list_email_templates` | `GET /{project}/agents/{agent_id}/email-templates` | `read:all` | `writer` | List email templates for an agent | | ||
| | `onboarding_get_changes_status` | `GET /{project}/changes-status` | `read:all` | `writer` | Check for unpublished/unsaved changes | | ||
| | `onboarding_get_integrations_config` | `GET /integrations-config` | `read:all` | `writer` | Get static agent integration definitions | | ||
|
|
||
| #### Phase 2 — Write Tools | ||
|
|
||
| | MCP Tool Name | Backend Endpoint | MCP Scope | V2 Relation | Description | | ||
| |---------------|-----------------|-----------|-------------|-------------| | ||
| | `onboarding_update_agent_config` | `PUT /{project}/agents/{agent_id}/config` | `manage:all` | `writer` | Create or update an agent's configuration | | ||
| | `onboarding_delete_agent_config` | `DELETE /{project}/agents/{agent_id}/config` | `manage:all` | `writer` | Delete an agent configuration | | ||
| | `onboarding_reorder_agents` | `PUT /{project}/agents/order` | `manage:all` | `writer` | Reorder agents by execution order | |
Reduce to one sequence diagram, trim tool inventory to the 4 onboarding tools + 1 Lens tool we actually need, remove implementation details that belong in code not in a review doc. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Joan Reyero <joan@reyero.io>
Add endpoint paths, HTTP methods, agent IDs, and AgentOS run schema
for all 4 onboarding tools. Preview and run agent tools use the AgentOS
framework POST /agents/{agent_id}/runs endpoint.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: Joan Reyero <joan@reyero.io>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Joan Reyero <joan@reyero.io>
Contributor
|
Closing this PR — the design doc it contained was evolved and committed as part of the implementation PR #39 (specifically commit ARCH-389 will remove |
emsearcy
added a commit
that referenced
this pull request
Apr 14, 2026
Replace the internal working doc docs/service-api-architecture.md (committed unintentionally in the implementation PR #39) with a canonical ARCHITECTURE.md at the repo root describing the current state of the system. Covers: - Overview with high-level elk flowchart - Client authn/authz: end-user OAuth2 JWT (PRM discovery, JWKS verify, scope gating), M2M client credentials, static API key stop-gap; stateless HTTP mode and per-request newServer() factory - Upstream authn/authz: CTE (RFC 8693) for end-user callers; MCP-server M2M V2 token for M2M/API-key callers; native V2 pass-through vs. MCP-brokered service APIs (OpenFGA gate + per-service M2M token) - Four end-to-end sequence diagrams covering all caller/upstream combinations Closes #27 (superseded by PR #39 / commit 8de2df8). 🤖 Generated with [GitHub Copilot](https://github.com/features/copilot) (via OpenCode) Signed-off-by: Eric Searcy <eric@linuxfoundation.org>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
What's in the doc
project:{uuid}#writerformat)writerfor onboarding,auditorfor LensReview requested
@ESearcy — please review the architecture and answer the open questions in section 10.
🤖 Generated with Claude Code