Connecting to the SD Elements MCP Server with OAuth

The SD Elements MCP server lets AI agents such as Claude, VS Code (GitHub Copilot), and ChatGPT/Codex work with SD Elements. With OAuth, users connect by signing in to SD Elements in their browser. They never copy or paste an API key, and the LLM is never exposed to the SDE API key or the OAuth token.

Supported agents

Only agents that support Client ID Metadata Documents (CIMD) are supported.

These clients are allowed by default:

  • Claude Code and Claude Desktop

  • GitHub Copilot with VS Code

  • ChatGPT Codex

Token lifetimes

Token Default lifetime Notes

Access token

1 hour

The client refreshes it automatically.

Refresh token

7 days

Replaced on every use. If an old refresh token is ever reused, SD Elements treats it as stolen and cancels the whole sign-in. The user must sign in again.

API token used by the MCP server

Never longer than the access token it came from

Held in the agent’s memory only — not exposed to the LLM.

After the refresh token expires, the user signs in again through the browser.

Setup guide

Follow these steps to configure and connect your MCP server.

Prerequisites

  • MCP server URL: The public address clients connect to (for example, https://your.instance.sdelements.com/mcp). If the server is behind a load balancer or reverse proxy, use the external URL.

Connecting with Claude Code

Add the server and sign in

  1. Add the MCP server. Run this command in your terminal:

    claude mcp add sdelements --transport http https://<your-mcp-server>/mcp

  2. Verify the connection. Start claude and enter the /mcp command. Check that the sdelements server is listed.

  3. Start authentication. Select the sdelements server and choose Authenticate.

  4. Open the browser. A browser window opens automatically. If it does not, copy the URL that Claude Code shows and paste it into your browser.

  5. Authorize access. Sign in with your SD Elements credentials, using your normal login or single sign-on. Click Authorize to give Claude Code access.

  6. Finish setup. When the browser shows the success screen, close the browser window and return to Claude Code.

Connecting with GitHub Copilot in VS Code

Before you start: clear any old sign-in

Do this if you have connected VS Code to this SD Elements MCP server before, with an API key or as a different SD Elements user. VS Code can keep an old sign-in and reuse it without asking you, so you might stay connected as the wrong user.

This is due to a current bug in VS Code (as of October 9, 2026). It is not caused by SD Elements, which rejects API keys once OAuth is on.

  1. Open the Command Palette: Ctrl+Shift+P on Windows and Linux, Cmd+Shift+P on macOS.

  2. Run Authentication: Remove Dynamic Authentication Providers.

  3. Select the entry for your SD Elements host and confirm.

  4. If the server is already in MCP Servers, restart it. VS Code then asks you to sign in again.

If you have never connected VS Code to this server, skip this step.

Add the server

  1. Open MCP Servers. In VS Code, open Agent Customizations and select MCP Servers in the sidebar. Click Add Server.

  2. Choose the server type. Pick HTTP (HTTP or Server-Sent Events).

  3. Enter the server URL. Type https://<your-mcp-server>/mcp and press Enter. Use https, not http.

  4. Enter the server ID. Type a name for the server, for example sdelements-oauth, and press Enter.

  5. Choose where to save it.

    • Global makes the server available in every workspace.

    • Workspace makes it available in the current workspace only.

  6. If you chose Global, pick the configuration file. Choose Copilot Global (~/.copilot/mcp-config.json). Do not choose User Configuration (deprecated).

  7. Check the saved configuration. VS Code opens the file it saved to.

    • If you chose Copilot Global, ~/.copilot/mcp-config.json

    • If you chose Workspace, mcp.json

    If the URL starts with http://, change it to https:// and save the file.

Sign in to SD Elements

The first time VS Code connects to the server, it asks you to sign in.

  1. Allow authentication. VS Code shows "The MCP Server Definition 'sdelements-oauth' wants to authenticate to <your-sde-host>". Click Allow.

  2. Open the sign-in page. VS Code asks "Do you want Code to open the external website?" and shows an address on your SD Elements host that begins with /o/authorize/. Click Open.

  3. Authorize in SD Elements. Your browser opens SD Elements. Sign in if you are asked to, using your normal login or single sign-on. The SD Elements MCP Server Authorization screen says the connection is limited to your existing user permissions. Click Authorize.

  4. Return to VS Code. The browser shows "Sign-in successful! Returning to Visual Studio Code…​". When the browser asks to open VS Code, click Open Visual Studio Code. To skip this prompt next time, tick Always allow first.

Confirm it works

  1. In MCP Servers, open sdelements-oauth. It should say No diagnostics to show. The SD Elements tools are now available in Copilot Chat.

Security summary

  • Sign-in happens in SD Elements, through your normal login and SSO. The AI client never sees the user’s password.

  • Client tokens do not work against the API. They are valid only for the MCP server.

  • Only the MCP server can turn a client token into API access, using a secret that never leaves your infrastructure.

  • The AI agent has exactly the user’s permissions, and every API call is recorded against the user.

  • Modern OAuth protections are on: PKCE is required, tokens are never accepted in URLs, refresh tokens rotate and detect reuse, and SD Elements stores token hashes, not usable tokens.

  • Only approved clients can connect, controlled by SDE_CIMD_ALLOWED_HOSTS.

Protect the MCP server’s client secret as you would an administrator credential. Anyone who holds it and a user’s client token can act as that user against the API.

Troubleshooting

Symptom Likely cause and fix

User sees a permission error after signing in

Their global role lacks Allow MCP server access.

401 for a client using an API key

Expected: API keys are rejected once OAuth is on.

VS Code (GitHub Copilot) connects as the wrong SD Elements user, or still connects after you removed the API key or OAuth was turned on

VS Code is reusing an old sign-in, due to a current bug in VS Code (as of October 9, 2026). Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P), run Authentication: Remove Dynamic Authentication Providers, select your SD Elements host, then restart the server in MCP Servers and sign in again.

Standards

For security reviewers, the implementation follows OAuth 2.1 and the MCP authorization specification:

  • Authorization code flow with PKCE (S256 only)

  • Client ID Metadata Documents for client identification; dynamic client registration is disabled

  • RFC 8707 resource indicators, so each token names the server it is for

  • RFC 8693 token exchange between the MCP server and the SD Elements API, with an act claim identifying the MCP server

  • RFC 9728 protected resource metadata and RFC 8414 authorization server metadata for discovery

  • RFC 9700 (OAuth security best current practice) protections, including issuer identification on the authorization response (RFC 9207)

results matching ""

    No results matching ""